[PATCH 0/2] Documentation: clarify usage of checkout

[PATCH 0/2] Documentation: clarify usage of checkout

[Chris Rorvick]

This is response to the questions posed in:

  http://thread.gmane.org/gmane.comp.version-control.git/211624

It doesn't seem like the behavior implemented in 70c9ac2 is documented.

Chris Rorvick (2):
  Documentation/git-checkout.txt: clarify usage
  Documentation/git-checkout.txt: document 70c9ac2 behavior

 Documentation/git-checkout.txt | 34 +++++++++++++++++++++++++---------
 1 file changed, 25 insertions(+), 9 deletions(-)

-- 
1.8.1.rc1.203.g1ddc124

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

[Chris Rorvick]

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.
+
 'git checkout' -b|-B <new_branch> [<start point>]::
-'git checkout' [--detach] [<commit>]::
 
-	This form switches branches by updating the index, working
-	tree, and HEAD to reflect the specified branch or commit.
-+
-If `-b` is given, a new branch is 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.
+	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.
+
 'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
 
 	When <paths> or `--patch` are given, 'git checkout' does *not*
-- 
1.8.1.rc1.203.g1ddc124

[PATCH 2/2] Documentation/git-checkout.txt: document 70c9ac2 behavior

[Chris Rorvick]

Document the behavior implemented in 70c9ac2 (DWIM "git checkout
frotz" to "git checkout -b frotz origin/frotz").

Signed-off-by: Chris Rorvick <chris@rorvick.com>
---
 Documentation/git-checkout.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index a47555c..db89cf7 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -25,6 +25,14 @@ branch.
 
 	Update the index, working tree, and HEAD to reflect the
 	specified 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
+equivalent to
++
+------------
+$ git checkout -b <branch> --track <remote>/<branch>
+------------
 
 'git checkout' -b|-B <new_branch> [<start point>]::
 
-- 
1.8.1.rc1.203.g1ddc124

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

[Junio C Hamano]

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

>  '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)...

Re: [PATCH 2/2] Documentation/git-checkout.txt: document 70c9ac2 behavior

[Junio C Hamano]

Chris Rorvick <chris@rorvick.com> writes:

> Document the behavior implemented in 70c9ac2 (DWIM "git checkout
> frotz" to "git checkout -b frotz origin/frotz").
>
> Signed-off-by: Chris Rorvick <chris@rorvick.com>
> ---
>  Documentation/git-checkout.txt | 8 ++++++++
>  1 file changed, 8 insertions(+)
>
> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index a47555c..db89cf7 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -25,6 +25,14 @@ branch.
>  
>  	Update the index, working tree, and HEAD to reflect the
>  	specified 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
> +equivalent to
> ++
> +------------
> +$ git checkout -b <branch> --track <remote>/<branch>
> +------------
>  
>  'git checkout' -b|-B <new_branch> [<start point>]::

Thanks; does it format well (I didn't check)?

Re: [PATCH 2/2] Documentation/git-checkout.txt: document 70c9ac2 behavior

[Andrew Ardill]

On 17 December 2012 18:21, Junio C Hamano <gitster@pobox.com> wrote:
> does it format well (I didn't check)?

It applied cleanly for me on latest master, and the output looked
consistent with existing documentation.

Regards,

Andrew Ardill

Re: [PATCH 2/2] Documentation/git-checkout.txt: document 70c9ac2 behavior

[Junio C Hamano]

Andrew Ardill <andrew.ardill@gmail.com> writes:

> On 17 December 2012 18:21, Junio C Hamano <gitster@pobox.com> wrote:
>> does it format well (I didn't check)?
>
> It applied cleanly for me on latest master, and the output looked
> consistent with existing documentation.

Thanks.

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

[Johannes Sixt]

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?

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

>> +
>> +	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)...

-- Hannes

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

[Junio C Hamano]

Here is what I tentatively have (so that I do not forget) on 'pu',
marked with "(squash???)", as a suggested update on top of Chris's
patches.

 Documentation/git-checkout.txt | 29 +++++++++++++++++++++--------
 1 file changed, 21 insertions(+), 8 deletions(-)

diff --git c/Documentation/git-checkout.txt w/Documentation/git-checkout.txt
index db89cf7..0e50eeb 100644
--- c/Documentation/git-checkout.txt
+++ w/Documentation/git-checkout.txt
@@ -21,10 +21,13 @@ or the specified tree.  If no paths are given, 'git checkout' will
 also update `HEAD` to set the specified branch as the current
 branch.
 
-'git checkout' [<branch>]::
+'git checkout' <branch>::
 
-	Update the index, working tree, and HEAD to reflect the
-	specified branch.
+	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>.
 +
 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
@@ -33,6 +36,11 @@ equivalent to
 ------------
 $ git checkout -b <branch> --track <remote>/<branch>
 ------------
++
+You could omit <branch>, in which case the command degenerates to
+"check out the current branch", which is a glorified no-op with a
+rather expensive side-effects to show only the tracking information,
+if exists, for the current branch.
 
 'git checkout' -b|-B <new_branch> [<start point>]::
 
@@ -54,12 +62,17 @@ $ git checkout <branch>
 that is to say, the branch is not reset/created unless "git checkout" is
 successful.
 
-'git checkout' [--detach] [<commit>]::
+'git checkout' --detach [<commit>]::
+'git checkout' <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 (see "DETACHED HEAD"
+	section), 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>.
++
+Passing `--detach` forces this behavior even if <commit> is a branch.
 
 'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
 

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

[Andrew Ardill]

Regards,

Andrew Ardill


On 17 December 2012 19:20, Johannes Sixt <j.sixt@viscovery.net> wrote:
> 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.

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

--

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

[Johannes Sixt]

Am 12/17/2012 9:48, schrieb Junio C Hamano:
> Here is what I tentatively have ...

Thanks!

> -'git checkout' [--detach] [<commit>]::
> +'git checkout' --detach [<commit>]::
> +'git checkout' <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 (see "DETACHED HEAD"
> +	section), 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>.

The last half-sentence should better be removed.

> ++
> +Passing `--detach` forces this behavior even if <commit> is a branch.
>  
>  'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::

-- Hannes

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

[Junio C Hamano]

Johannes Sixt <j.sixt@viscovery.net> writes:

> Am 12/17/2012 9:48, schrieb Junio C Hamano:
>> Here is what I tentatively have ...
>
> Thanks!
>
>> -'git checkout' [--detach] [<commit>]::
>> +'git checkout' --detach [<commit>]::
>> +'git checkout' <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 (see "DETACHED HEAD"
>> +	section), 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>.
>
> The last half-sentence should better be removed.

True; we do not have a particular "on the <branch>" in this state.
At least, "on the <branch>" needs to be removed.  But I think we may
want a more different wording here, including the earlier "work on
building new history on top of" part.

The detached HEAD state primarily is a sightseeing mode, where the
user is expected to view but not touch.  Even for experienced users,
commits on a detached HEAD are for keeping snapshots of interim
states during a throw-away experiment, so the purpose of detaching
is not exactly "to work on *building* new history" in the first
place.

Carefree experimentation is encouraged by not forbidding commmits
from this state, with the expectation that:

 (1) if it does not lead to interesting result, another "git
     checkout <branch>" will wipe the throw-away experiment without
     affecting any of your more important branches; and

 (2) an experiment that yielded something useful can be further
     polished on a concrete branch by "git checkout -b <newbranch>".

I think the above discussion on detached HEAD can be added to its
own section.

	Prepare to work on top of <commit>, by detaching HEAD at it
	(see "DETACHED HEAD" section), and updating te index and the
	files in the working tree.  Local modifications to the files
	in the working tree are kept, so that the resulting working
	tree will be the state recorded in the commit plus the local
	modifications.

Or something, perhaps?

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

[Philip Oakley]

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

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

[Junio C Hamano]

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

So your suggestion is going backwards, I'd have to say.

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

[Andrew Ardill]

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

--

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

[Junio C Hamano]

Andrew Ardill <andrew.ardill@gmail.com> writes:

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

I've been deliberately avoiding the term "switch", actually.  I
agree that it may be familiar to people with prior exposure to
subversion, but that is not the primary audience of the manual.

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

I agree with you that sightseeing use case where you do not intend
to make any commit is also important.  That is exactly why I said
"further work is done on that branch" not "to that branch" in the
message you are responding to.

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

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com> Sent: Monday, December 17, 
2012 9:13 PM
> "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.

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 

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

[Andrew Ardill]

On 18 December 2012 08:59, Junio C Hamano <gitster@pobox.com> wrote:
> Andrew Ardill <andrew.ardill@gmail.com> writes:
>> 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.
>
> I've been deliberately avoiding the term "switch", actually.  I
> agree that it may be familiar to people with prior exposure to
> subversion, but that is not the primary audience of the manual.

I don't have much experience with svn, so I didn't make that
connection. Independent of svn usage, what is wrong with the term
'switch'?

I would be interested to hear how translators communicate the checkout
concept, as I assume the word checkout doesn't exist in many
languages. For me, switching between revisions is a natural way of
phrasing the action, but perhaps there is a better way of saying the
same thing?

>> 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.
>
> I agree with you that sightseeing use case where you do not intend
> to make any commit is also important.  That is exactly why I said
> "further work is done on that branch" not "to that branch" in the
> message you are responding to.

Ah ok, I didn't pick up on that nuance. Your suggestion from earlier
has, for example, "Prepare to work on building new history on
<branch>" which *is* excluding that use case. Perhaps modifying
similar lines to something like "Prepare to work with the
repository/history/something from <branch>" or maybe just "Prepare to
work with <branch>" would better encapsulate those use cases.
Following lines would expand on what it means to work with a branch or
commit, and the technical details of updates to the repositories
current state.

Regards,

Andrew Ardill

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> I agree with you that sightseeing use case where you do not intend
> to make any commit is also important.  That is exactly why I said
> "further work is done on that branch" not "to that branch" in the
> message you are responding to.

Here is a work-in-progress relative to Chris's 83c9989
(Documentation/git-checkout.txt: document 70c9ac2 behavior,
2012-12-17).

Even though "switch to that specific branch" may be easy to grasp as
a concept, I do not think "switch to detached HEAD" makes much
sense, so I ended up with "switch" for the <branch> case, and
"detach" for the "--detach" one, at least for now.

diff --git c/Documentation/git-checkout.txt w/Documentation/git-checkout.txt
index db89cf7..dcf1a32 100644
--- c/Documentation/git-checkout.txt
+++ w/Documentation/git-checkout.txt
@@ -21,10 +21,12 @@ or the specified tree.  If no paths are given, 'git checkout' will
 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.
+'git checkout' <branch>::
+	To prepare for working on <branch>, switch to it 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 to 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
@@ -33,6 +35,11 @@ equivalent to
 ------------
 $ git checkout -b <branch> --track <remote>/<branch>
 ------------
++
+You could omit <branch>, in which case the command degenerates to
+"check out the current branch", which is a glorified no-op with a
+rather expensive side-effects to show only the tracking information,
+if exists, for the current branch.
 
 'git checkout' -b|-B <new_branch> [<start point>]::
 
@@ -54,12 +61,17 @@ $ git checkout <branch>
 that is to say, the branch is not reset/created unless "git checkout" is
 successful.
 
-'git checkout' [--detach] [<commit>]::
+'git checkout' --detach [<commit>]::
+'git checkout' <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 top of <commit>, by detaching HEAD at it
+	(see "DETACHED HEAD" section), and updating the index and the
+	files in the working tree.  Local modifications to the files
+	in the working tree are kept, so that the resulting working
+	tree will be the state recorded in the commit plus the local
+	modifications.
++
+Passing `--detach` forces this behavior even if <commit> is a branch.
 
 'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
 

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

[Andrew Ardill]

I like these, and I think they are conveying the right amount of
information. There is a slight discrepancy between the <branch> and
<commit> versions, where it seems we are assuming that by checking out
a commit you are intending to work 'on top of' it. This could be
avoided by using the term 'with' in both cases. Also, they are in
different tenses, but I'm not sure which is preferred ('Prepare to' vs
'To prepare for').

In the second tense, these opening lines might look like this:

+       To prepare for working with <branch>, switch to it by updating

+       To prepare for working with <commit>, detach HEAD at it
+       (see "DETACHED HEAD" section), and update the index and the
+       files in the working tree.


Regards,

Andrew Ardill

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

[Chris Rorvick]

On Mon, Dec 17, 2012 at 2:20 AM, Johannes Sixt <j.sixt@viscovery.net> wrote:
>>> +'git checkout' [--detach] [<commit>]::
>
> The title here is better spelled as two lines:
>
> 'git checkout' <commit>::
> 'git checkout' --detach <branch>::

AsciiDoc renders these horizontally separated by a comma when
formatted as a man page instead of vertically as written (and as
rendered by the HTML documentation.)  I think this makes this
separation into two less effective, but at least it doesn't line wrap
on an 80-wide terminal like the previous title did.

Chris

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

[Chris Rorvick]

On Mon, Dec 17, 2012 at 7:53 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Here is a work-in-progress relative to Chris's 83c9989
> (Documentation/git-checkout.txt: document 70c9ac2 behavior,
> 2012-12-17).

It sounds pretty good to me.

> @@ -54,12 +61,17 @@ $ git checkout <branch>
>  that is to say, the branch is not reset/created unless "git checkout" is
>  successful.
>
> -'git checkout' [--detach] [<commit>]::
> +'git checkout' --detach [<commit>]::
> +'git checkout' <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 top of <commit>, by detaching HEAD at it
> +       (see "DETACHED HEAD" section), and updating the index and the
> +       files in the working tree.  Local modifications to the files
> +       in the working tree are kept, so that the resulting working
> +       tree will be the state recorded in the commit plus the local
> +       modifications.
> ++
> +Passing `--detach` forces this behavior even if <commit> is a branch.
>
>  'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
>

I like Johannes' suggestion of using "<branch>" in the --detach case
instead of "<commit>" as I think it makes the reason for the
separation more obvious at a glance.  On top of your changes, maybe
something like:

--->8---
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index dcf1a32..4fdf41a 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -61,8 +61,8 @@ $ git checkout <branch>
 that is to say, the branch is not reset/created unless "git checkout" is
 successful.

-'git checkout' --detach [<commit>]::
 'git checkout' <commit>::
+'git checkout' --detach [<branch>]::

        Prepare to work on top of <commit>, by detaching HEAD at it
        (see "DETACHED HEAD" section), and updating the index and the
@@ -71,7 +71,8 @@ successful.
        tree will be the state recorded in the commit plus the local
        modifications.
 +
-Passing `--detach` forces this behavior even if <commit> is a branch.
+Passing `--detach` forces this behavior in the case of a <branch>, or
+the current branch if one is not specified.

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

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

[Junio C Hamano]

Chris Rorvick <chris@rorvick.com> writes:

> I like Johannes' suggestion of using "<branch>" in the --detach case
> instead of "<commit>" as I think it makes the reason for the
> separation more obvious at a glance.

Sounds sensible; even though the option does not require its
argument to be a branch name, the user does not have a reason to use
the option if it is not giving a branch name, either, so it all
balances out ;-).

>
> --->8---
> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index dcf1a32..4fdf41a 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -61,8 +61,8 @@ $ git checkout <branch>
>  that is to say, the branch is not reset/created unless "git checkout" is
>  successful.
>
> -'git checkout' --detach [<commit>]::
>  'git checkout' <commit>::
> +'git checkout' --detach [<branch>]::
>
>         Prepare to work on top of <commit>, by detaching HEAD at it
>         (see "DETACHED HEAD" section), and updating the index and the
> @@ -71,7 +71,8 @@ successful.
>         tree will be the state recorded in the commit plus the local
>         modifications.
>  +
> -Passing `--detach` forces this behavior even if <commit> is a branch.
> +Passing `--detach` forces this behavior in the case of a <branch>, or
> +the current branch if one is not specified.
>
>  'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::