From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 17 Oct 2013 22:55:08 +0000 (-0700)
Subject: Merge branch 'jc/checkout-detach-doc'
X-Git-Tag: v1.8.5-rc0~45
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/ff6e1b887f6f038b7e8d7aaea2ca19d9add03607?hp=83f18cdd71d9154c9b563d13c502dd475b3ac88c

Merge branch 'jc/checkout-detach-doc'

"git checkout [--detach] <commit>" was listed poorly in the
synopsis section of its documentation.

* jc/checkout-detach-doc:
checkout: update synopsys and documentation on detaching HEAD
---

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index ca118ac6bf..91294f89c8 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -9,7 +9,8 @@ SYNOPSIS
 --------
 [verse]
 'git checkout' [-q] [-f] [-m] [<branch>]
-'git checkout' [-q] [-f] [-m] [--detach] [<commit>]
+'git checkout' [-q] [-f] [-m] --detach [<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' [-p|--patch] [<tree-ish>] [--] [<paths>...]
@@ -62,7 +63,7 @@ that is to say, the branch is not reset/created unless "git checkout" is
 successful.
 
 'git checkout' --detach [<branch>]::
-'git checkout' <commit>::
+'git checkout' [--detach] <commit>::
 
 	Prepare to work on top of <commit>, by detaching HEAD at it
 	(see "DETACHED HEAD" section), and updating the index and the
@@ -71,10 +72,11 @@ successful.
 	tree will be the state recorded in the commit plus the local
 	modifications.
 +
-Passing `--detach` forces this behavior in the case of a <branch> (without
-the option, giving a branch name to the command would check out the branch,
-instead of detaching HEAD at it), or the current commit,
-if no <branch> is specified.
+When the <commit> argument is a branch name, the `--detach` option can
+be used to detach HEAD at the tip of the branch (`git checkout
+<branch>` would check out that branch without detaching HEAD).
++
+Omitting <branch> detaches HEAD at the tip of the current branch.
 
 'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::