On Wed, Jun 10, 2015 at 08:05:32AM -0700, Junio C Hamano wrote: > Torsten Bögershausen <tbo...@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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
