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

Torsten Bögershausen [off-list ref] writes:

On 2015-06-10 17.05, Junio C Hamano wrote:

quoted

quoted

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

I guess 'replace' would be a better word than 'restore' for the current
behaviour.

-- 
Ed Avis [off-list ref]