From: "Philip Oakley" <philipoakley@iee.org>
To: "Christoph Michelbach" <michelbach94@gmail.com>,
"Git Mailing List" <git@vger.kernel.org>
Subject: Re: [PATCH] Documentation/git-checkout: make doc. of checkout <tree-ish> clearer
Date: Sun, 16 Apr 2017 22:25:56 +0100 [thread overview]
Message-ID: <DF5E72F5BD2F4BB99D8EC4DF1B4543F7@PhilipOakley> (raw)
In-Reply-To: 1492368692.22852.9.camel@gmail.com
From: "Christoph Michelbach" <michelbach94@gmail.com>
> On Sun, 2017-04-16 at 19:03 +0100, Philip Oakley wrote:
>> From: "Christoph Michelbach" <michelbach94@gmail.com>
>> >
>> > On Sun, 2017-04-16 at 00:28 +0100, Philip Oakley wrote:
>> > >
>> > > From: "Christoph Michelbach" <michelbach94@gmail.com>
>> > > >
>> > > >
>> > > > While technically in the documentation, the fact that changes
>> > > > introduced by a checkout <tree-ish> are staged automatically,
>> > > > was
>> > > > not obvious when reading its documentation. It is now
>> > > > specifically
>> > > > pointed out.
>> > > >
>> > > > Signed-off-by: Christoph Michelbach <michelbach94@gmail.com>
>> > > > ---
>> > > > 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 <branch> detaches HEAD at the tip of
>> > > > the
>> > > > current branch.
>> > > > 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
>> > > 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] [<tree-ish>] [--] [<paths>…]
>> invocation.
>
> It's: git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>...
The one I quoted is direct from the Synopsis, which does indicate there are
potentially more aspects to resolve, such as the influence of using the
[-p|--patch] options.
It maybe that the paragraph / sentence that needs adjusting is;
'git checkout' with <paths> or `--patch` is used to restore modified or
deleted paths to their original contents from the index or replace paths
with the contents from a named <tree-ish> (most often a commit-ish).
and split it at the "or replace paths" option to pick out your specific
case.
>
> 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] [<tree-ish>] [--]
> <pathspec>...` 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 <michelbach94@gmail.com>
> ---
> 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 <branch> detaches HEAD at the tip of the
> current branch.
> 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
Ah yes, "specify a specific" does sound a bit tautological.
> - (i.e. commit, tag or tree) to update the index for the given
> - paths before updating the working tree.
> + <tree-ish> 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 <paths> or `--patch` is used to restore modified or
> deleted paths to their original contents from the index or replace
> paths
> --
> 2.7.4
>
>
> --
> Christoph
>
next prev parent reply other threads:[~2017-04-16 21:26 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 [this message]
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
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=DF5E72F5BD2F4BB99D8EC4DF1B4543F7@PhilipOakley \
--to=philipoakley@iee.org \
--cc=git@vger.kernel.org \
--cc=michelbach94@gmail.com \
/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).