Re: [PATCH] Documentation/git-checkout: make doc. of checkout <tree-ish> clearer

[Christoph Michelbach <michelbach94@gmail.com>]

I'm sorry, somehow my email client deleted half of your message when I saved it
when replying. I only noticed this when wanting to delete your email and noticed
that it was pretty long.

--------------------------------------------------------------------------------

On Sun, 2017-04-23 at 18:55 -0700, Junio C Hamano wrote:
> Christoph Michelbach <michelbach94@gmail.com> writes:
> > From: Christoph Michelbach <michelbach94@gmail.com>
> > Date: Sat, 22 Apr 2017 18:49:57 +0200
> > Subject: [PATCH] Doc./git-checkout: correct doc. of checkout
> > <pathspec>...
> > 
> > The previous documentation states that the named paths are
> > updated both in the index and the working tree. This is not
> > correct as those paths can point to folders which are not
> > updated to what they are in the given tree-ish. Rather,
> > the files pointed to by the pathspecs are copied from the
> s/pointed to by/that match/

Ok.


> > 
> > tree-ish to the index and working tree One difference being
> Missing full-stop after "tree".

Oops.


> > 
> > that one can name paths which are not present in the working
> > tree ...
> That one is not a difference, I would think.  If your current index
> and working tree lack F, you give pathspec that match F, and the
> tree-ish has that path F, that named path _is_ updated both in the
> index and in the working tree.

I don't think it's inherently obvious that you can name paths which don't
occur in the working tree if it's stated that those are updated. For
something to be updated, I suppose it has to exist in the first place. But I
don't really want to discuss the commit message as everyone even reading it
already knows how the command works so I just removed it.
> >  	When <paths> or `--patch` are given, 'git checkout' does *not*
> > +	switch branches.  It copies the files matching the pathspecs in
> > +	<tree-is> (i.e. a commit, tag, or tree) to the index and
> <tree-ish> is misspelled here.  Drop (i.e. ...) as (1) it is not
> correct (a tag may not point at a tree-ish) and (2) "checkout" is
> not a place to learn what a tree-ish is (glossary is).

Done.

> 
> > 
> > +	subsequently to the working directory, overwriting changes
> Do we need to say "subsequently" when we are aiming to be more
> intelligible by not describing the order of execution?  The end
> result is that the blobs named by the pathspecs from the tree-ish
> are checked out to the index and to the working tree at the same
> time.

I agree. Done.


> 
> > 
> > +...	Note that because the index is updated, the
> > +	changes introduced by this command are automatically staged.
> This is redundant and unnecessary, I would say.  If you absolutely
> need to say this, at least drop "automatically".  There is nothing
> automatic about it.  The user is asking to checkout the named blobs
> out of the tree-ish to the index and to the working tree, and Git is
> merely doing as it was told.

Done.


> In addition the description is fuzzy; what are "changes introduced
> by this command" relative to?  If you did "checkout HEAD path" after
> editing path in the working tree, is "reverting my edit" the
> "changes introduced by this command"?

All of those no changes which could possibly be staged are immediately staged.
All statements about all elements of the empty set are true.


> If you did "checkout HEAD
> path" after editing path, "git add path" and then editing path
> further, what are the "changes introduced by this command"?

The command can't introduce any further changes just because you edit files
after it has already terminated execution.



From fe0d1298cf4de841af994f4d9f72d49e25edea00 Mon Sep 17 00:00:00 2001
From: Christoph Michelbach <michelbach94@gmail.com>
Date: Sat, 22 Apr 2017 18:49:57 +0200
Subject: [PATCH] Doc./git-checkout: correct doc. of checkout <pathspec>...

The previous documentation states that the named paths are
updated both in the index and the working tree. This is not
correct as those paths can point to folders which are not
updated to what they are in the given tree-ish. Rather,
the files which match the pathspecs are copied from the
tree-ish to the index and working tree. The difference being
that only files which are already present in the given
tree-ish are affected.

Furthermore, the changed text is intended to be more
intelligible as it is written in a way which is easy to
follow, rather than describing the technical process in
order of execution.

A hint alerting the users that changes introduced by this
command when naming a tree-ish are automatically staged has
been introduced.

Signed-off-by: Christoph Michelbach <michelbach94@gmail.com>
---
 Documentation/git-checkout.txt | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 8e2c066..ea3b4df 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -81,13 +81,14 @@ Omitting <branch> detaches HEAD at the tip of the current
branch.
 'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
 
 	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
-	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.
+	switch branches.  It copies the files matching the pathspecs in
+	<tree-ish> to the index and to the working tree, overwriting
+	changes	(including deletion of files) in those files.  In this
+	case, the -b and --track options are meaningless and giving either
+	of them results in an error.  Note that because the index is updated,
+	the changes introduced by this command are staged.  If no tree-ish is
+	provided, the current index is used and remains unchanged, modifying
+	only the working tree.
 +
 'git checkout' with <paths> or `--patch` is used to restore modified or
 deleted paths to their original contents from the index or replace paths
-- 
2.7.4