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

[Andrew Ardill <andrew.ardill@gmail.com>]

On 18 December 2012 08:13, Junio C Hamano <gitster@pobox.com> wrote:
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> From: "Junio C Hamano" <gitster@pobox.com> Sent: Monday, December 17,
>>> This is to "check out the branch" ;-)
>>> ...
>>
>> From a user perspective it's better to refer to the working directory
>> first rather than the internal mechanics.
>>
>>    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.
>
> I agree that the mention of "pointing HEAD to" may be better to be
> rephrased in the user facing terms.
>
> Because the primary purpose of "git checkout <branch>" is to "check
> out the branch so that further work is done on that branch", that
> aspect of the behaviour should be mentioned first.  Updating of the
> working tree files and the index is the implemenation detail of
> starting to work on that branch.

Even if the primary purpose of "git checkout <branch>" is to "check
out the branch so that further work is done on that branch", I don't
believe that means it has to be stated first. In fact, I would say
that there are enough other use cases that the language should be
slightly more use-case agnostic in the first situation. For example,
someone might switch to another branch or commit simply to see what
state the tree was in at that point. Some people use checkout to
deploy a tag of the working tree onto a production server. The first
example in particular is, I think, a common enough operation that
restricting the opening lines of documentation to talking about
building further work is misleading.

My earlier submission dealt with this by using the 'Switch to the
specified ...' terminology. For me this is implicitly stating 'Switch
the state of the repository to be the same as the specified ...' but
perhaps it would do to be more explicit? I prefer the shorter form
myself.

By following this with the typical use case it makes it clear what the
intended use of the command is, and some idea about the mechanics of
its function.

I realised that my signature was improperly placed when I submitted my
suggestion last, so I will include it here as reference for anyone who
skipped over it. It builds on top of the two original patches.

Regards,

Andrew Ardill

-->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>...::

--