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

[Junio C Hamano <gitster@pobox.com>]

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

> git checkout <pathspec> can be used to revert changes in the working tree.

I somehow thought that concensus in the recent thread was that
"restore", not "revert", is the more appropriate wording?

And I think that is indeed sensible because "revert" (or "reset")
already means something else in Git (and in other systems), while
"restore" does not have a confusing connotation.  It can only mean
"overwrite with a pristine copy", which is what the command is
about.

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

>  
>  SYNOPSIS
>  --------
> @@ -83,7 +83,8 @@ Omitting <branch> detaches HEAD at the tip of the current branch.
>  	When <paths> or `--patch` are given, 'git checkout' does *not*
>  	switch branches.  It updates the named paths in the working tree
>  	from the index file or from a named <tree-ish> (most often a
> -	commit).  In this case, the `-b` and `--track` options are
> +	commit).  Changes in files are discarded and deleted files are
> +	restored.

I see we are suffering from the common disease of giving one
explanation and then realizing that first explanation can be
misread, clarifying it by more explanation, after reading the
updated text three times.  Let's instead try to clarify the first
explanation to make it harder to misread.

In this case, "updates X from Y" is what causes misunderstanding, as
"updates" does not necessarily mean "restores with the original".

How about this?

  	'git checkout' with <paths> or `--patch` is used to restore
        modified or deleted paths to their original contents from
        the index file or from a named <tree-ish> (most often a
        commit) without switching branches.