checkout: introduce --detach synonym for "git checkout foo^{commit}"

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 66e570113a077d2c52c4fc3ac09d24a272df5301..d162117e7156fdf18754261b22cb024475960f46 100644 (file)
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -9,6 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'git checkout' [-q] [-f] [-m] [<branch>]
+'git checkout' [-q] [-f] [-m] [--detach] [<commit>]
 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
 'git checkout' --patch [<tree-ish>] [--] [<paths>...]
@@ -22,9 +23,10 @@ branch.
 
 'git checkout' [<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.
+       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
@@ -45,14 +47,14 @@ successful.
 
 'git checkout' [--patch] [<tree-ish>] [--] <pathspec>...::
 
-       When <paths> or `--patch` are given, 'git checkout' *not* switch
-       branches.  It updates the named paths in the working tree from
-       the index file or from a named <tree-ish> (most often a commit).  In
-       this case, the `-b` and `--track` options are meaningless and giving
-       either of them results in an error. The <tree-ish> argument can be
-       used to specify a specific tree-ish (i.e. commit, tag or tree)
-       to update the index for the given paths before updating the
-       working tree.
+       When <paths> or `--patch` are given, 'git checkout' does *not*
+       switch branches.  It updates the named paths in the working tree
+       from the index file or from a named <tree-ish> (most often a
+       commit).  In this case, the `-b` and `--track` options are
+       meaningless and giving either of them results in an error.  The
+       <tree-ish> argument can be used to specify a specific tree-ish
+       (i.e.  commit, tag or tree) to update the index for the given
+       paths before updating the working tree.
 +
 The index may contain unmerged entries because of a previous failed merge.
 By default, if you try to check out such an entry from the index, the
@@ -115,6 +117,13 @@ explicitly give a name with '-b' in such a case.
        Create the new branch's reflog; see linkgit:git-branch[1] for
        details.
 
+--detach::
+       Rather than checking out a branch to work on it, check out a
+       commit for inspection and discardable experiments.
+       This is the default behavior of "git checkout <commit>" when
+       <commit> is not a branch name.  See the "DETACHED HEAD" section
+       below for details.
+
 --orphan::
        Create a new 'orphan' branch, named <new_branch>, started from
        <start_point> and switch to it.  The first commit made on this
@@ -187,7 +196,7 @@ As a special case, the `"@\{-N\}"` syntax for the N-th last branch
 checks out the branch (instead of detaching).  You may also specify
 `-` which is synonymous with `"@\{-1\}"`.
 +
-As a further special case, you may use `"A...B"` as a shortcut for the
+As a further special case, you may use `"A\...B"` as a shortcut for the
 merge base of `A` and `B` if there is exactly one merge base. You can
 leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
 
@@ -204,7 +213,7 @@ leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
 
 
 
-Detached HEAD
+DETACHED HEAD
 -------------
 
 It is sometimes useful to be able to 'checkout' a commit that is