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

> Christoph Michelbach <michelbach94@gmail.com> writes:
> 
> > 
> > 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.
> Please separate your discussion from the patch proper.  Check
> Documentation/SubmittingPatches and send a proper patch like other
> people do.
> 
> 
> > 
> > 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>...
> These we take from the e-mail header.  You usually remove them from
> the body of the message (and move the Subject: to e-mail subject), hence
> 
> > 
> > The previous documentation states that the named paths are
> this line will become the first line in the body of the message.
> 
> > 
> > A hint alerting the users that changes introduced by this
> > command when naming a tree-ish are automatically staged has
> > been introduced.
> We are still saying automatically here?
> 
> > 
> > Signed-off-by: Christoph Michelbach <michelbach94@gmail.com>
> > ---
> >  Documentation/git-checkout.txt | 15 ++++++++-------
> >  1 file changed, 8 insertions(+), 7 deletions(-)
> This is not limited to your message, but from time to time, I see
> messages with SP substituted with non-breaking space like the above
> two lines (and they appear in the patch text).  I can still read and
> comment on the patch, but it is unusuable as an input to "git am" to
> be applied.  I wonder where these NBSP come from---perhaps some
> commmon MUAs corrupt text messages like this?
> 
> > 
> > 
> > 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
> I am debating myself if rephrasing "in <tree-ish>" to "from
> <tree-ish>" makes the result clearer to understand.  When we say
> "Copy files from T to I and W", it would be obvious that what does
> not exist in T will not be copied.
> 
> I also wonder "If no-tree-ish is provided" at the end of this
> paragraph you have is a bit too far from the above primary point of
> the description, because you have an unrelated "In this case,
> -b/-t...", in between.  
> 
> 	The blobs matching the pathspecs are checked out from the
> 	index to the working tree.  Optionally, when <tree-ish> is
> 	given, the blobs matching the pathspecs from the <tree-ish>
> 	is copied to the index before that happens.
> 
> is what I would want to say, but obviously that does not describe
> what happens in the chronological order, so it is the most clear
> description for people who understand what is written, but it will
> take two reading until the reader gets to that stage X-<.
> 
> Perhaps the unrelated "In this case, the -b..." should go first; it
> is part of "does *not* switch branches".  Also even with your patch,
> it starts with "X is not Y" and does not clearly say "X is Z".
> 
> 	When <paths> or `--patch` ar given, 'git checkout' does
> 	*not* switch branches (giving the `-b` and `--track` options
> 	will cause an error, as they are meaningless).  It checks
> 	out paths out of the <tree-ish> (if given) and the index to
> 	the to working tree.  When an optional <tree-ish> is given
> 	blobs in the <tree-ish> that match <pathspec> are copied to
> 	the index.  The blobs that match <pathspec> are then copied
> 	from the index to the working tree, overwriting what is in
> 	(or missing from) the working tree.
> 
> May be an improvement (i.e. say what Z is: checking out paths from
> tree-ish and/or index to the working tree).  By explicitly phrasing
> that <tree-ish>, from which the index is updated, is optional, it is
> clear that without <tree-ish> there is no update to the index.
> "missing from" covers two cases: (1) the user removed the file from
> the working tree and <tree-ish>, e.g. HEAD, has the file, hence
> removed one is resurrected; (2) the user didn't touch the file and
> HEAD didn't have it, but by checking out from <tree-ish> that has
> the file, the user added that new file to the set of files the user
> is working with.
> 
> Hmm?
>