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

From: Scott Schmit <i.grok@comcast.net>
Date: Jun 12, 2015, 04:49 UTC
Message-ID: <20150612044906.GA17424@odin.ulthar.us>
In-Reply-To: <xmqqioavob7n.fsf@gitster.dls.corp.google.com>

On Wed, Jun 10, 2015 at 08:05:32AM -0700, Junio C Hamano wrote:

Show 47 quoted lines

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

I think these changes would improve the above:

s/index file/index/
- index file is implementation; the glossary only defines "index"

s/or from/or replace paths with the contents from/
- the latter case isn't always restoration, if <tree-ish> doesn't come
  from an ancestor of HEAD (so I don't like "restore" in the summary
  either)

s/without switching/instead of switching/
- 'without' implies it makes sense to restore/replace with switching
  branches, but we've chosen not to.  (I then waste time trying to
  understand that)

s/commit/commit-ish/
- tags are also tree-ishes, though you could argue this case is less
  "often"

leaving:

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

does a sha1 count as "named"? Maybe s/named //.

-- 
Scott Schmit