checkout: update synopsys and documentation on detaching HEAD

In the synopsis, the second form to detach HEAD at the named commit
labelled the argument as '<commit>'.  While this is technically more
correct, because the feature to detach is not limited to the tip of
a named branch, it was found confusing and did not express the fact
that you have to give `--detach` if you are naming the commit you
want to detach HEAD at with a branch name.

Separate this case into two syntactical forms, mimicking the way how
the DESCRIPTION section shows this usage.  Also update the text that
explains the syntax to name the commit to detach HEAD at to clarify.

Suggested-by: Benjamin Bergman <ben@benbergman.ca>
Helped-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
1 file changed
tree: 0dcaed754439b23774bb63fa500edc77eaceb0de
  1. block-sha1/
  2. builtin/
  3. compat/
  4. contrib/
  5. Documentation/
  6. git-gui/
  7. git_remote_helpers/
  8. gitk-git/
  9. gitweb/
  10. mergetools/
  11. perl/
  12. po/
  13. ppc/
  14. t/
  15. templates/
  16. vcs-svn/
  17. xdiff/
  18. .gitattributes
  19. .gitignore
  20. .mailmap
  21. abspath.c
  22. aclocal.m4
  23. advice.c
  24. advice.h
  25. alias.c
  26. alloc.c
  27. archive-tar.c
  28. archive-zip.c
  29. archive.c
  30. archive.h
  31. argv-array.c
  32. argv-array.h
  33. attr.c
  34. attr.h
  35. base85.c
  36. bisect.c
  37. bisect.h
  38. blob.c
  39. blob.h
  40. branch.c
  41. branch.h
  42. builtin.h
  43. bulk-checkin.c
  44. bulk-checkin.h
  45. bundle.c
  46. bundle.h
  47. cache-tree.c
  48. cache-tree.h
  49. cache.h
  50. check-builtins.sh
  51. check-racy.c
  52. check_bindir
  53. color.c
  54. color.h
  55. column.c
  56. column.h
  57. combine-diff.c
  58. command-list.txt
  59. commit-slab.h
  60. commit.c
  61. commit.h
  62. config.c
  63. config.mak.in
  64. config.mak.uname
  65. configure.ac
  66. connect.c
  67. connected.c
  68. connected.h
  69. convert.c
  70. convert.h
  71. copy.c
  72. COPYING
  73. credential-cache--daemon.c
  74. credential-cache.c
  75. credential-store.c
  76. credential.c
  77. credential.h
  78. csum-file.c
  79. csum-file.h
  80. ctype.c
  81. daemon.c
  82. date.c
  83. decorate.c
  84. decorate.h
  85. delta.h
  86. diff-delta.c
  87. diff-lib.c
  88. diff-no-index.c
  89. diff.c
  90. diff.h
  91. diffcore-break.c
  92. diffcore-delta.c
  93. diffcore-order.c
  94. diffcore-pickaxe.c
  95. diffcore-rename.c
  96. diffcore.h
  97. dir.c
  98. dir.h
  99. editor.c
  100. entry.c
  101. environment.c
  102. exec_cmd.c
  103. exec_cmd.h
  104. fast-import.c
  105. fetch-pack.c
  106. fetch-pack.h
  107. fmt-merge-msg.h
  108. fsck.c
  109. fsck.h
  110. generate-cmdlist.sh
  111. gettext.c
  112. gettext.h
  113. git-add--interactive.perl
  114. git-am.sh
  115. git-archimport.perl
  116. git-bisect.sh
  117. git-compat-util.h
  118. git-cvsexportcommit.perl
  119. git-cvsimport.perl
  120. git-cvsserver.perl
  121. git-difftool--helper.sh
  122. git-difftool.perl
  123. git-filter-branch.sh
  124. git-instaweb.sh
  125. git-lost-found.sh
  126. git-merge-octopus.sh
  127. git-merge-one-file.sh
  128. git-merge-resolve.sh
  129. git-mergetool--lib.sh
  130. git-mergetool.sh
  131. git-p4.py
  132. git-parse-remote.sh
  133. git-pull.sh
  134. git-quiltimport.sh
  135. git-rebase--am.sh
  136. git-rebase--interactive.sh
  137. git-rebase--merge.sh
  138. git-rebase.sh
  139. git-relink.perl
  140. git-remote-testgit.sh
  141. git-remote-testpy.py
  142. git-repack.sh
  143. git-request-pull.sh
  144. git-send-email.perl
  145. git-sh-i18n.sh
  146. git-sh-setup.sh
  147. git-stash.sh
  148. git-submodule.sh
  149. git-svn.perl
  150. GIT-VERSION-GEN
  151. git-web--browse.sh
  152. git.c
  153. git.rc
  154. git.spec.in
  155. gpg-interface.c
  156. gpg-interface.h
  157. graph.c
  158. graph.h
  159. grep.c
  160. grep.h
  161. hash.c
  162. hash.h
  163. help.c
  164. help.h
  165. hex.c
  166. http-backend.c
  167. http-fetch.c
  168. http-push.c
  169. http-walker.c
  170. http.c
  171. http.h
  172. ident.c
  173. imap-send.c
  174. INSTALL
  175. kwset.c
  176. kwset.h
  177. levenshtein.c
  178. levenshtein.h
  179. LGPL-2.1
  180. line-log.c
  181. line-log.h
  182. line-range.c
  183. line-range.h
  184. list-objects.c
  185. list-objects.h
  186. ll-merge.c
  187. ll-merge.h
  188. lockfile.c
  189. log-tree.c
  190. log-tree.h
  191. mailmap.c
  192. mailmap.h
  193. Makefile
  194. match-trees.c
  195. merge-blobs.c
  196. merge-blobs.h
  197. merge-recursive.c
  198. merge-recursive.h
  199. merge.c
  200. mergesort.c
  201. mergesort.h
  202. name-hash.c
  203. notes-cache.c
  204. notes-cache.h
  205. notes-merge.c
  206. notes-merge.h
  207. notes-utils.c
  208. notes-utils.h
  209. notes.c
  210. notes.h
  211. object.c
  212. object.h
  213. pack-check.c
  214. pack-revindex.c
  215. pack-revindex.h
  216. pack-write.c
  217. pack.h
  218. pager.c
  219. parse-options-cb.c
  220. parse-options.c
  221. parse-options.h
  222. patch-delta.c
  223. patch-ids.c
  224. patch-ids.h
  225. path.c
  226. pathspec.c
  227. pathspec.h
  228. pkt-line.c
  229. pkt-line.h
  230. preload-index.c
  231. pretty.c
  232. prio-queue.c
  233. prio-queue.h
  234. progress.c
  235. progress.h
  236. prompt.c
  237. prompt.h
  238. quote.c
  239. quote.h
  240. reachable.c
  241. reachable.h
  242. read-cache.c
  243. README
  244. reflog-walk.c
  245. reflog-walk.h
  246. refs.c
  247. refs.h
  248. remote-curl.c
  249. remote-testsvn.c
  250. remote.c
  251. remote.h
  252. replace_object.c
  253. rerere.c
  254. rerere.h
  255. resolve-undo.c
  256. resolve-undo.h
  257. revision.c
  258. revision.h
  259. run-command.c
  260. run-command.h
  261. send-pack.c
  262. send-pack.h
  263. sequencer.c
  264. sequencer.h
  265. server-info.c
  266. setup.c
  267. sh-i18n--envsubst.c
  268. sha1-array.c
  269. sha1-array.h
  270. sha1-lookup.c
  271. sha1-lookup.h
  272. sha1_file.c
  273. sha1_name.c
  274. shallow.c
  275. shell.c
  276. shortlog.h
  277. show-index.c
  278. sideband.c
  279. sideband.h
  280. sigchain.c
  281. sigchain.h
  282. strbuf.c
  283. strbuf.h
  284. streaming.c
  285. streaming.h
  286. string-list.c
  287. string-list.h
  288. submodule.c
  289. submodule.h
  290. symlinks.c
  291. tag.c
  292. tag.h
  293. tar.h
  294. test-chmtime.c
  295. test-ctype.c
  296. test-date.c
  297. test-delta.c
  298. test-dump-cache-tree.c
  299. test-genrandom.c
  300. test-index-version.c
  301. test-line-buffer.c
  302. test-match-trees.c
  303. test-mergesort.c
  304. test-mktemp.c
  305. test-parse-options.c
  306. test-path-utils.c
  307. test-prio-queue.c
  308. test-read-cache.c
  309. test-regex.c
  310. test-revision-walking.c
  311. test-run-command.c
  312. test-scrap-cache-tree.c
  313. test-sha1.c
  314. test-sha1.sh
  315. test-sigchain.c
  316. test-string-list.c
  317. test-subprocess.c
  318. test-svn-fe.c
  319. test-wildmatch.c
  320. thread-utils.c
  321. thread-utils.h
  322. trace.c
  323. transport-helper.c
  324. transport.c
  325. transport.h
  326. tree-diff.c
  327. tree-walk.c
  328. tree-walk.h
  329. tree.c
  330. tree.h
  331. unimplemented.sh
  332. unix-socket.c
  333. unix-socket.h
  334. unpack-trees.c
  335. unpack-trees.h
  336. upload-pack.c
  337. url.c
  338. url.h
  339. usage.c
  340. userdiff.c
  341. userdiff.h
  342. utf8.c
  343. utf8.h
  344. varint.c
  345. varint.h
  346. version.c
  347. version.h
  348. walker.c
  349. walker.h
  350. wildmatch.c
  351. wildmatch.h
  352. wrap-for-bin.sh
  353. wrapper.c
  354. write_or_die.c
  355. ws.c
  356. wt-status.c
  357. wt-status.h
  358. xdiff-interface.c
  359. xdiff-interface.h
  360. zlib.c