"Philip Oakley" [off-list ref] writes:
From: "Junio C Hamano" <redacted> Sent: Monday, December 17,
quoted
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.
So your suggestion is going backwards, I'd have to say.
On 18 December 2012 08:13, Junio C Hamano [off-list ref] wrote:
"Philip Oakley" [off-list ref] writes:
quoted
From: "Junio C Hamano" <redacted> Sent: Monday, December 17,
quoted
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 <redacted>
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 <redacted>
---
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>...::
--
From: "Junio C Hamano" <redacted> Sent: Monday, December 17,
2012 9:13 PM
"Philip Oakley" [off-list ref] writes:
quoted
From: "Junio C Hamano" <redacted> Sent: Monday, December 17,
quoted
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.
That part is OK, but it is a bit tautological.
Updating of the
working tree files and the index is the implemenation detail of
starting to work on that branch.
It was this part that I felt needed the worker's work-tree mentioned
first.
It could be argued that workers think they do work on the tree, and that
the branch name is an administrative place holder.
When the two sentences are back to back it was OK, as you had still
included the key element of my suggestion.
So your suggestion is going backwards, I'd have to say.
A misunderstanding of the suggestion perhaps?
Philip