From: Christoph Michelbach Date: Sun, 16 Apr 2017 18:51:32 GMT Subject: Re: [PATCH] Documentation/git-checkout: make doc. of checkout clearer Message-ID: <1492368692.22852.9.camel@gmail.com> In-Reply-To: <2DCA89C3FDFF41E5B3651018BF837267@PhilipOakley> On Sun, 2017-04-16 at 19:03 +0100, Philip Oakley wrote: > From: "Christoph Michelbach" > > > > On Sun, 2017-04-16 at 00:28 +0100, Philip Oakley wrote: > > > > > > From: "Christoph Michelbach" > > > > > > > > > > > > While technically in the documentation, the fact that changes > > > > introduced by a checkout are staged automatically, > > > > was > > > > not obvious when reading its documentation. It is now > > > > specifically > > > > pointed out. > > > > > > > > Signed-off-by: Christoph Michelbach > > > > --- > > > > Documentation/git-checkout.txt | 7 ++++--- > > > > 1 file changed, 4 insertions(+), 3 deletions(-) > > > > > > > > diff --git a/Documentation/git-checkout.txt > > > > b/Documentation/git-checkout.txt > > > > index 8e2c066..cfd7b18 100644 > > > > --- a/Documentation/git-checkout.txt > > > > +++ b/Documentation/git-checkout.txt > > > > @@ -85,9 +85,10 @@ Omitting detaches HEAD at the tip of > > > > the > > > > current branch. > > > > from the index file or from a named (most often a > > > > commit). In this case, the `-b` and `--track` options are > > > > meaningless and giving either of them results in an error. The > > > > - argument can be used to specify a specific tree-ish > > > > - (i.e. commit, tag or tree) to update the index for the given > > > Do these lines above actually need reflowing? Their content hasn't > > > changed > > > making it more difficult to spot the significant changes below > > > here. > > They're just part of the context of the automatically created patch. > The lines with +/- markings are the actual change lines. It's the > lines > without them that are the context lines. > > It does sound like an accidental reflow where the "(i.e." moved > between > lines, and the "paths" moved for the following lines. > > If reflowing is required it's normal to put it in a separate patch so > that  > each type of change gets its own commit message. Ah, right. I added a missing "to" and changed "to specify a specific". > > > For a clean commit checkout my mental model is not one of anything > > > new > > > being > > > actively staged i.e. different from what was in the commit. > > Note that this is not about something like `git checkout 925b29` but > > about > > something like > > `git checkout 925b29 src`. > Yes, that was the part I was getting at. > > The commit message (and the patch context) doesn't quite give enough > to see  > that is is particular to the - > > git checkout [-p|--patch] [] [--] […]invocation. It's: git checkout [-p|--patch] [] [--] ... The paths aren't optional. Added it to the commit message: While technically in the documentation, the fact that changes introduced by a `git checkout [-p|--patch] [] [--] ...` are staged automatically, was not obvious when reading its documentation. It is now specifically pointed out. Related sentence cleaned up. Signed-off-by: Christoph Michelbach ---  Documentation/git-checkout.txt | 7 ++++---  1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git- checkout.txt index 8e2c066..cfd7b18 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -85,9 +85,10 @@ Omitting detaches HEAD at the tip of the current branch.         from the index file or from a named (most often a         commit).  In this case, the `-b` and `--track` options are         meaningless and giving either of them results in an error.  The -        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. +        argument can be used to specify the tree-ish (i.e. +       commit, tag, or tree) to update the index to for the given paths +       before updating the working tree accordingly.  Note that this means +       that the changes this command introduces are staged automatically.  +  'git checkout' with or `--patch` is used to restore modified or  deleted paths to their original contents from the index or replace paths --  2.7.4 -- Christoph