Re: [PATCH] git-checkout.txt: Document "git checkout <pathspec>" better

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 12, 2015, 16:24 UTC
Message-ID: <xmqqa8w4evyx.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20150612044906.GA17424@odin.ulthar.us>

Scott Schmit <i.grok@comcast.net> writes:

Show 13 quoted lines

> On Wed, Jun 10, 2015 at 08:05:32AM -0700, Junio C Hamano wrote:
>
>> How about this?
>> 
>>         'git checkout' with <paths> or `--patch` is used to restore
>>         modified or deleted paths to their original contents from
>>         the index file or from a named <tree-ish> (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 <tree-ish> 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.

Show 6 quoted lines

> leaving:
>
> 'git checkout' with <paths> 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 <tree-ish> (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 <tree-ish>/the <tree-ish>/ in the improved text you proposed above would be sufficient, I would think, as it is clear which <tree-ish> we are talking about in the context.

Thanks.