Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage

["Philip Oakley" <philipoakley@iee.org>]

From: "Junio C Hamano" <gitster@pobox.com> Sent: Monday, December 17,
2012 7:21 AM
> Chris Rorvick <chris@rorvick.com> writes:
>
>> The forms of checkout that do not take a path are lumped together in
>> the
>> DESCRIPTION section, but the description for this group is dominated
>> by
>> explanation of the -b|-B form.  Split these apart for more clarity.
>>
>> Signed-off-by: Chris Rorvick <chris@rorvick.com>
>> ---
>>  Documentation/git-checkout.txt | 26 +++++++++++++++++---------
>>  1 file changed, 17 insertions(+), 9 deletions(-)
>>
>> diff --git a/Documentation/git-checkout.txt
>> b/Documentation/git-checkout.txt
>> index 7958a47..a47555c 100644
>> --- a/Documentation/git-checkout.txt
>> +++ b/Documentation/git-checkout.txt
>> @@ -22,17 +22,18 @@ also update `HEAD` to set the specified branch as
>> the current
>>  branch.
>>
>>  'git checkout' [<branch>]::
>> +
>> + Update the index, working tree, and HEAD to reflect the
>> + specified branch.
>
> This is to "check out the branch" ;-)
>
> But of course, we cannot define "checkout" in terms of "checkout",
> so we need to phrase it without saying "checkout" and explain what
> it *means* to check out the branch.
>
> I am not sure "Reflect" is a good word.  Making the result similar
> to the branch is only one aspect of the act of checking out the
> branch. The other equally important aspect is that this is done to
> advance the history of the branch.
>
> Perhaps...
>
> Prepare to work on building new history on <branch>, by
> pointing the HEAD to the branch and updating the index and
> the files in the working tree.  Local modifications to the
> files in the working tree are kept, so that they can be
> committed on the <branch>.

>From a user perspective it's better to refer to the working directory
first rather than the internal mechanics. Perhaps:

    Prepare to work on <branch>, by updating the files in the
    working tree and index to the branch's previous content, and
    pointing HEAD to it.

    Local modifications to the files in the working tree are kept,
    so that they can be committed on the <branch>.

>
>>  'git checkout' -b|-B <new_branch> [<start point>]::
>>
>> + Specifying `-b` causes a new branch to be created as if
>> + linkgit:git-branch[1] were called and then checked out.  In
>> + this case you can use the `--track` or `--no-track` options,
>> + which will be passed to 'git branch'.  As a convenience,
>> + `--track` without `-b` implies branch creation; see the
>> + description of `--track` below.
>>  +
>>  If `-B` is given, <new_branch> is created if it doesn't exist;
>> otherwise, it
>>  is reset. This is the transactional equivalent of
>> @@ -45,6 +46,13 @@ $ git checkout <branch>
>>  that is to say, the branch is not reset/created unless "git
>> checkout" is
>>  successful.
>>
>> +'git checkout' [--detach] [<commit>]::
>> +
>> + Update the index and working tree to reflect the specified
>> + commit and set HEAD to point directly to <commit> (see
>> + "DETACHED HEAD" section.)  Passing `--detach` forces this
>> + behavior even if <commit> is a branch.
>
> Prepare to work on building new history on top of <commit>,
>        by detaching HEAD at the commit and ...(likewise)...