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

["Torsten Bögershausen" <tboegi@web.de>]

On 2015-06-17 18.19, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
> 
>> Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
>>
>>> Yes, but "Switch branchs or discard local changes" still does not
>>> describe "git checkout HEAD^^^ -- file.txt" (restore to an old state,
>>> but does not switch branch) or "git checkout -- file.txt" (get from the
>>> index).
>>
>> You are right, especially when file.txt does not have any change
>> relative to HEAD, there is no "discarding" going on.  You are
>> actively introducing a change to an unchanged file by checking
>> contents out of a different revision.
>>
>>> To me, "discard local changes" imply that there will be no uncommited
>>> changes on the files implied in the command after the operation.
>>
>> Yup.
> 
> What was discussed in this thread sounded suspiciously familiar ;-).
> 
> Unfortunately "overwrite changes in the working tree" and "discard
> local changes" are equally bad.  As it does not say overwrite with
> what, we invite the original confusion that triggered these threads
> if the reader thought an equally useful but different "overwrites
> with result of merging your local changes to the pristine" (similar
> to what "checkout -m" does) would happen.
> 
> At least, "restore working tree files" without saying "restoring
> them to what state?" is much less likely to cause such a confusion.
> 
> So perhaps
> 
>     git-checkout - Switch branches or restore working tree files
> 
> in the headline, and then explain "restore to what state" in the
> description?
I'm not sure if the "restore" is always the right thing to describe:
'git checkout <commit> -- <path>'
will "copy" the version from another commit into the workspace.

My v3 will probably use the original line:
git-checkout - Checkout a branch or paths to the working tree

(and improve the description)

git-checkout - Checkout a branch or paths to the working tree