From: Christoph Michelbach <michelbach94@gmail.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: Philip Oakley <philipoakley@iee.org>,
Git Mailing List <git@vger.kernel.org>
Subject: Re: [PATCH] Documentation/git-checkout: make doc. of checkout <tree-ish> clearer
Date: Tue, 25 Apr 2017 11:11:23 +0200 [thread overview]
Message-ID: <1493111483.18809.0.camel@gmail.com> (raw)
In-Reply-To: <xmqqzif5xo9m.fsf@gitster.mtv.corp.google.com>
I give up. Bye.
On Mon, 2017-04-24 at 18:35 -0700, Junio C Hamano wrote:
> 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?
>
next prev parent reply other threads:[~2017-04-25 9:11 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-04-15 20:17 [PATCH] Documentation/git-checkout: make doc. of checkout <tree-ish> clearer Christoph Michelbach
2017-04-15 23:28 ` Philip Oakley
2017-04-16 13:01 ` Christoph Michelbach
2017-04-16 18:03 ` Philip Oakley
2017-04-16 18:51 ` Christoph Michelbach
2017-04-16 21:25 ` Philip Oakley
2017-04-16 22:06 ` Christoph Michelbach
2017-04-17 16:04 ` Philip Oakley
[not found] ` <1492452173.11708.22.camel@gmail.com>
2017-04-17 20:59 ` Philip Oakley
2017-04-18 0:31 ` Junio C Hamano
2017-04-18 12:26 ` Christoph Michelbach
2017-04-19 1:40 ` Junio C Hamano
2017-04-22 17:12 ` Christoph Michelbach
2017-04-24 1:55 ` Junio C Hamano
2017-04-24 12:24 ` Christoph Michelbach
2017-04-24 12:46 ` Christoph Michelbach
2017-04-25 1:35 ` Junio C Hamano
2017-04-25 9:11 ` Christoph Michelbach [this message]
2017-04-19 7:32 ` Philip Oakley
2017-04-18 11:50 ` Christoph Michelbach
2017-04-18 0:26 ` Junio C Hamano
2017-04-18 12:02 ` Christoph Michelbach
2017-04-19 8:14 ` Philip Oakley
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1493111483.18809.0.camel@gmail.com \
--to=michelbach94@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=philipoakley@iee.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).