Merge branch 'jc/doc-checkout' into maint

Doc update.

* jc/doc-checkout:
checkout doc: clarify command line args for "checkout paths" mode

diff --combined Documentation/git-checkout.txt
index bd268a8fccc32a1d218b30d58a688353a0fe236f,236f324698911c1cc198d4d61f0d8696b132d8d0..e108b0f74bb6dc4d9f3fc27e7c3fe571b19a9d2f
--- 1/Documentation/git-checkout.txt
--- 2/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@@ -13,7 -13,8 +13,8 @@@ SYNOPSI
  '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>...]
+ 'git checkout' [<tree-ish>] [--] <pathspec>...
+ 'git checkout' (-p|--patch) [<tree-ish>] [--] [<paths>...]
  
  DESCRIPTION
  -----------
@@@ -38,7 -39,7 +39,7 @@@ $ git checkout -b <branch> --track <rem
  ------------
  +
  You could omit <branch>, in which case the command degenerates to
 -"check out the current branch", which is a glorified no-op with a
 +"check out the current branch", which is a glorified no-op with
  rather expensive side-effects to show only the tracking information,
  if exists, for the current branch.
  
@@@ -78,20 -79,13 +79,13 @@@ be used to detach HEAD at the tip of th
  +
  Omitting <branch> detaches HEAD at the tip of the current branch.
  
- 'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::
+ 'git checkout' [<tree-ish>] [--] <pathspec>...::
  
-       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.
- +
- 'git checkout' with <paths> or `--patch` is used to restore modified or
- deleted paths to their original contents from the index or replace paths
- with the contents from a named <tree-ish> (most often a commit-ish).
+       Overwrite paths in the working tree by replacing with the
+       contents in the index or in the <tree-ish> (most often a
+       commit).  When a <tree-ish> is given, the paths that
+       match the <pathspec> are updated both in the index and in
+       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
@@@ -101,6 -95,14 +95,14 @@@ specific side of the merge can be check
  using `--ours` or `--theirs`.  With `-m`, changes made to the working tree
  file can be discarded to re-create the original conflicted merge result.
  
+ 'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]::
+       This is similar to the "check out paths to the working tree
+       from either the index or from a tree-ish" mode described
+       above, but lets you use the interactive interface to show
+       the "diff" output and choose which hunks to use in the
+       result.  See below for the description of `--patch` option.
+ 
+ 
  OPTIONS
  -------
  -q::