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

[Christoph Michelbach <michelbach94@gmail.com>]

On Tue, 2017-04-18 at 18:40 -0700, Junio C Hamano wrote:
> Christoph Michelbach <michelbach94@gmail.com> writes:
> 
> > 
> > On Mon, 2017-04-17 at 17:31 -0700, Junio C Hamano wrote:
> > 
> > > 
> > > Obviously, "grab all paths that match <pathspec> out of <tree>,
> > > add
> > > them to the index and copy them out to the working tree" will
> > > never
> > > be able to _restore_ the lack of 'd', even it may match the
> > > <pathspec> being used to do this checkout, by removing it from the
> > > current index and the working tree.
> > Exactly. "grab all paths that match <pathspec> out of <tree>, add
> > them
> > to the index and copy them out to the working tree" is a more
> > accurate
> > description of what the command does (but it might need some
> > rewording
> > ;-) ).
> Of course it is accurate, as that is how I would write it, not
> "restore", if I were doing the documentation.
> 
> Care to send in a patch to update the documentation?

From 10c362b0632255f90e0975fb6656feedca5fd407 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 pointed to by the pathspecs are copied from the
tree-ish to the index and working tree One difference being
that one can name paths which are not present in the working
tree and another 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..f74f237 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 directory, 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 directory.
 +
 '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