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

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

Junio C Hamano <[email-masked]> writes:

> Matthieu Moy <[email-masked]> 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?