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

[Christoph Michelbach <michelbach94@gmail.com>]

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.


From 24a5ca5affbe8a09413b72ceb3cb50ae2fe9fd2b 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 | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 8e2c066..306b9d2 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -81,13 +81,15 @@ 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-is> (i.e. a commit, tag, or tree) to the index and
+	subsequently 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 automatically 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