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

From: Junio C Hamano <[email-masked]>
Date: Wed, 17 Jun 2015 12:58:06 -0700

Torsten Bögershausen <[email-masked]> writes:

> On 2015-06-17 21.23, Junio C Hamano wrote:
> []
>>> Basically, I'm fine with anything starting with "Switch branches or",
>>> but please do change the headline ;-).
>> 
>> Likewise; I agree "switch branches or" part is good.
>
> How about this:
>
> git-checkout - Switch branches or restore changes to the working tree

Gahh.  We are NOT restoring CHANGES.  We are restoring the whole
contents to a path.

It is perfectly fine to do this:

	git reset --hard
        git checkout HEAD^ hello.c

There is no changes in hello.c after "reset --hard".

This is what makes it tempting for me to say "check out (an existing
contents to) a working tree file".

Moreover, it does not matter if the target file is changed or not in
the first place, so your added text:

>> '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).

that says "restoring modified or deleted is from the index,
replacing is from a tree-ish" is placing a stress on a wrong spot, I
would think.

"Checkout individual files" is to "replace contents with existing
versions, taken either from the index or from a named tree-ish."
That is done in preparation to come up with the suitable contents
for specified paths.

This is a tangent, but on the other hand, "checkout a whole branch"
is to prepare the working tree to be used to modify the specified
branch.  And that is why the word "checkout" makes sense for both
operations.