Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
- From
Andrew Ardill <andrew.ardill@gmail.com>
- Date
- Dec 17, 2012, 21:50 UTC
- Message-ID
- <CAH5451nVe1VcD3VzCO7EtKSkzv9CyJs=uqQ9MkMTJEXMTwEvmw@mail.gmail.com>
- In-Reply-To
- <7v1ueol6ut.fsf@alter.siamese.dyndns.org>
On 18 December 2012 08:13, Junio C Hamano <gitster@pobox.com> wrote:
Show 21 quoted lines
> "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>...:: --