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

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 10, 2015, 15:05 UTC
Message-ID: <xmqqioavob7n.fsf@gitster.dls.corp.google.com>
In-Reply-To: <5575F948.4060400@web.de>

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

Show 10 quoted lines

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