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

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 17, 2015, 19:58 UTC
Message-ID: <xmqq8ubi6rap.fsf@gitster.dls.corp.google.com>
In-Reply-To: <5581CAA6.5080306@web.de>

Torsten Bögershausen <tboegi@web.de> writes:

Show 10 quoted lines

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