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

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 11, 2015, 14:47 UTC
Message-ID: <xmqqegligv45.fsf@gitster.dls.corp.google.com>
In-Reply-To: <55788190.80106@web.de>

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

Show 9 quoted lines

> On 2015-06-10 17.05, Junio C Hamano wrote:
>
>>> -git-checkout - Checkout a branch or paths to the working tree
>>> +git-checkout - Switch branches or reverts changes in the working tree
>> 
>> Two verbs in different moods; either "switch branches or restore
>> changes" or "switches branches or restores changes" would fix that,
>> and judging from "git help" output, I think we want to go with the
>> former, i.e. "switch branches or restore changes".

Gaah, no we do not "restore" changes. We "restore" working tree files to their pristine state.

And "... or restore working tree files to their pristine state" is way too long.

Unfortunately "overwrite changes in the working tree" is even worse. As it does not say overwrite _with what_, we invite the original confusion that triggered this whole thread 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...

    git-checkout - Switch branches or restore working tree files

perhaps?