Christoph Michelbach <michelbach94@xxxxxxxxx> 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@xxxxxxxxx> > 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@xxxxxxxxx> > --- > 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?