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>...:: -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html