Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:55:33
Possibly related (same subject, not in this thread)
- 2016-06-15 · Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage · Andrew Ardill <hidden>
- 2016-06-15 · Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage · Chris Rorvick <hidden>
- 2016-06-15 · Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage · Junio C Hamano <hidden>
- 2016-06-15 · [PATCH 1/2] Documentation/git-checkout.txt: clarify usage · Chris Rorvick <hidden>
- 2016-06-15 · Re: [PATCH 1/2] Documentation/git-checkout.txt: clarify usage · Junio C Hamano <hidden>
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>...::