patchgit-checkout.txt: Document "git checkout <pathspec>" better

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

Signed-off-by: Torsten Bögershausen <tboegi@web.de>
---
My first attempt to improve the documentation

 Documentation/git-checkout.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

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

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.

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

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.

'restore' may be more consistent with git's internal terminology. But from an outsider's perspective, 'revert' rather than 'restore' is in my view much clearer and more consistent with other version control systems: for example 'svn revert' is what you use to revert files in the working copy.

The original issue was that I naively expected that 'git checkout PATH' would indeed just 'restore' some files, that is, create them when they are missing. Its action is rather more drastic than that.

If 'revert' is not a suitable verb because of the existing git-revert, then I suggest that 'overwrite' or 'replace' might better convey the idea of what the command does.

Ed Avis <eda@waniasset.com> writes:

The reason why I said "restore" is because it does *not* have any "internal terminology" connotation.

On the other hand, "revert" that means "create a counter-effect commit" is not "internal". "git revert" is a part of end-user facing command.

The only people that will be helped by using "revert" there will be the ones who haven't learned "git revert". And it will make it harder for them to learn "git revert". It is unfortunate that other systems use the word "revert" in a different way, and that is why we should avoid using that word when describing "checkout".

Git is about "contents", not "files". You modify a file, and restore its contents to its pristine state. It is not "restore the file", as Git is not about "files".

I think "overwrite is better" is primarily coming from not thinking in terms of "Git tracks contents, not files".

I agree, the word 'revert' is already taken for the operation of creating a new commit which undoes some earlier commit. So 'revert' cannot be used for the operation of overwriting a working tree file with its contents from the repository.

But just because 'revert' is not a good choice, doesn't mean that 'restore' is either.

'Restore to its pristine state' does convey the flavour of what happens. Plain 'restore' by itself doesn't, really.

But 'git checkout .' is primarily an operation on the local filesystem. As far as I know, it does not change the git repository, nor the index, stashes and so on. Its only effect is to create and overwrite local files, much the same as 'tar x'. So the appropriate language to describe it should be based more in common usage rather than git-specific terms - if indeed 'restore' is the git-specific term for replacing a file in the working tree. (In which case why not call the command 'git restore'?)

If indeed it did work by tracking contents, there wouldn't be a problem. The old contents of the file could be saved as a stash and then the file's contents replaced with the version from the current commit.

% git checkout .
The following files have been restored to their pristine state:
   foo
The previous contents have been saved and can be got back with:
   git stash apply checkout_backup_abcde

Then there would be no need for agonizing over the documentation to make it clear that 'git checkout PATH' can be a dangerous operation, because it would no longer be dangerous.

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

(Need to drop Eric from CC-list( 

OK for me

[]

OK for me.

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

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 <eda@waniasset.com> writes:

Hmm, but wouldn't replace have the same issue as overwrite, namely, 'replace with what?'.

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

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 <i.grok@comcast.net> writes:

Yup, that was sloppy of me.  Thanks.

Yes, that is why the original said 'checkout' in the first place.

OK.

Correct.

Yeah, I like that. I'd appreciate if somebody can submit the final version as a patch form after waiting for a few days to hear other's opinions.

The "named" in the original "named tree-ish" does not mean "the tree-ish has a human readable name (e.g. a tag)"; it merely means "the user tells Git to use one tree-ish to use for this operation; and the tree-ish was specified (by some means) by the user", i.e. the same thing as "specified". If you specify the tree-ish with its object name, yes, you are naming that (after all, that is what everything in sha1-name.c does).

s/a named <tree-ish>/the <tree-ish>/ in the improved text you proposed above would be sufficient, I would think, as it is clear which <tree-ish> we are talking about in the context.

Thanks.

On 2015-06-12 06.49, Scott Schmit wrote:

------------------- I will probably send a patch, the next days or so. It feels as if we can split the long sentence, and differntiate between the "restore" and "copy content from other tree-sh". How about this:

'git checkout' [--] <pathspec>...::
	'git checkout' with <paths> is used to restore modified or
	deleted paths to their original contents from the index.

'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
	'git checkout' with [<tree-ish>] and <paths> or `--patch` is used
	to replace <paths> with the contents from a named <tree-ish>
	(most often a commit-ish) instead of switching branches.
	In this case, the `-b` and `--track` options are
	meaningless and giving either of them results in an error.  The
	<tree-ish> argument can be used to specify a specific tree-ish
	(i.e.  commit, tag or tree) to update the index for the given
	paths before updating the working tree.
+