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

From: Andrew Ardill <andrew.ardill@gmail.com>
Date: Dec 17, 2012, 08:53 UTC
Message-ID: <CAH5451=U47Aastune7==e67nK9X4A9khdtZvKzhpwkC-eR=o8A@mail.gmail.com>
In-Reply-To: <50CED5D4.5040705@viscovery.net>

Regards,

Andrew Ardill

On 17 December 2012 19:20, Johannes Sixt <j.sixt@viscovery.net> wrote:

Show 7 quoted lines

> Am 12/17/2012 8:21, schrieb Junio C Hamano:
>> Chris Rorvick <chris@rorvick.com> writes:
>>>  'git checkout' [<branch>]::
>
> Is <branch> really optional in this form?
>
> BTW, what does plain 'git checkout' do? Just report ahead/behind information?

I think it defaults to either HEAD or the current branch, which shows uncommitted changes and relationship to upstream.

Show 12 quoted lines

>>> +
>>> +    Update the index, working tree, and HEAD to reflect the
>>> +    specified branch.
> ...
>>> +'git checkout' [--detach] [<commit>]::
>
> The title here is better spelled as two lines:
>
> 'git checkout' <commit>::
> 'git checkout' --detach <branch>::
>
> I don't think that <commit> or <branch> should be indicated as optional here.

doing 'git checkout --detach' will detach from the current branch if you have one, but maybe listing <branch> as optional would work in that case?

Here is my suggestion, differing from what Junio put forward primarily by first indicating that a checkout is a 'switch' to a different branch or commit. This makes sense to me, and is used elsewhere in the documentation, so I thought it might make sense here too.

-->8--

From: Andrew Ardill <andrew.ardill@gmail.com>
Date: Mon, 17 Dec 2012 18:53:41 +1100
Subject: [PATCH] Documentation/git-checkout.txt: Use consistent terminology

git checkout is described as 'switching' branches in places. Use this terminology more consistently.

Expand on the purpose of switching to a branch or commit, which is typically to prepare to build history on top of that branch or commit.

Signed-off-by: Andrew Ardill <andrew.ardill@gmail.com>
---
 Documentation/git-checkout.txt | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index db89cf7..e6db14f 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -23,8 +23,11 @@ branch.

 'git checkout' [<branch>]::

-       Update the index, working tree, and HEAD to reflect the
-       specified branch.
+       Switch to the specified <branch>. Prepares for building new
+       history on <branch>, by updating the index and the files in the
+       working tree, and by pointing HEAD at the branch. Local
+       modifications to the files in the working tree are kept, so that
+       they can be committed on the <branch>.
 +
 If <branch> is not found but there does exist a tracking branch in
 exactly one remote (call it <remote>) with a matching name, treat as
@@ -56,10 +59,13 @@ 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.
+       Switch to the specified <commit>. Prepares for building new
+       history on top of <commit>, by updating the index and the files
+       in the working tree, and by pointing HEAD at <commit>. Local
+       modifications to the files in the working tree are kept, so that
+       they can be committed on top of <commit>. Passing `--detach`
+       forces HEAD to point directly at <commit> even if <commit> is a
+       branch (see "DETACHED HEAD" section.)

 'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::

--