From: Junio C Hamano Date: Fri, 12 Jun 2015 16:24:06 GMT Subject: Re: [PATCH] git-checkout.txt: Document "git checkout " better Message-ID: In-Reply-To: <20150612044906.GA17424@odin.ulthar.us> Scott Schmit writes: > On Wed, Jun 10, 2015 at 08:05:32AM -0700, Junio C Hamano wrote: > >> How about this? >> >> 'git checkout' with or `--patch` is used to restore >> modified or deleted paths to their original contents from >> the index file or from a named (most often a >> commit) without switching branches. > > I think these changes would improve the above: > > s/index file/index/ > - index file is implementation; the glossary only defines "index" Yup, that was sloppy of me. Thanks. > s/or from/or replace paths with the contents from/ > - the latter case isn't always restoration, if doesn't come > from an ancestor of HEAD (so I don't like "restore" in the summary > either) Yes, that is why the original said 'checkout' in the first place. > s/without switching/instead of switching/ > - 'without' implies it makes sense to restore/replace with switching > branches, but we've chosen not to. (I then waste time trying to > understand that) OK. > s/commit/commit-ish/ > - tags are also tree-ishes, though you could argue this case is less > "often" Correct. > leaving: > > 'git checkout' with or `--patch` is used to restore modified or > deleted paths to their original contents from the index or replace paths > with the contents from a named (most often a commit-ish) > instead of switching branches. Yeah, I like that. I'd appreciate if somebody can submit the final version as a patch form after waiting for a few days to hear other's opinions. > does a sha1 count as "named"? Maybe s/named //. The "named" in the original "named tree-ish" does not mean "the tree-ish has a human readable name (e.g. a tag)"; it merely means "the user tells Git to use one tree-ish to use for this operation; and the tree-ish was specified (by some means) by the user", i.e. the same thing as "specified". If you specify the tree-ish with its object name, yes, you are naming that (after all, that is what everything in sha1-name.c does). s/a named /the / in the improved text you proposed above would be sufficient, I would think, as it is clear which we are talking about in the context. Thanks.