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

3 messages, 3 authors, 2016-06-15 · open the first message on its own page

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

From: Junio C Hamano <hidden>
Date: 2016-06-15 22:55:33

Junio C Hamano [off-list ref] 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

From: Andrew Ardill <hidden>
Date: 2016-06-15 22:55:33

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

From: Chris Rorvick <hidden>
Date: 2016-06-15 22:55:33

On Mon, Dec 17, 2012 at 7:53 PM, Junio C Hamano [off-list ref] 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.

quoted hunk

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

`h`	back out one level
`j`	next message in thread
`k`	previous message in thread
`l`	drill in
`Esc`	close help / fold thread tree
`?`	toggle this help