There are "git checkout [-p][<tree-ish>][--][<paths>...]" in the SYNOPSIS section, and "git checkout [-p][<tree-ish>][--]<paths>..." as the header for the section that explains the "check out paths from index/tree-ish" mode. It is unclear if we require at least one path, or it is entirely optional.
Actually, both are wrong. Without the "-p(atch)" option, you must have <pathspec> (otherwise, with a commit that is a <tree-ish>, you would be checking out that commit to build a new history on top of it). With it, it is already clear that you are checking out paths, it is optional. In other words, you cannot omit both. The source of the confusion is that -p(atch) is described as if it is just another "optional" part and its description is lumped together with the non patch mode, even though the actual end user experience is vastly different. Let's split the entry into two, and describe the regular mode and the patch mode separately. This allows us to make it clear that the regular mode MUST be given at least one pathspec, that the patch mode can be invoked with either '-p' or '--patch' but one of these must be given, and that the pathspec is entirely optional in the patch mode. Also, revamp the explanation of "checkout paths" by removing extraneous description at the beginning, that says "checking out paths is not checking out a branch". Explaining what it is for and when the user wants to use it upfront is the most direct way to help the readers. Noticed-by: Robert P J Day Signed-off-by: Junio C Hamano <gits...@pobox.com> --- * As people burned braincycles discussing this earlier already, let's try to tie the loose end to help future readers of the manual. Documentation/git-checkout.txt | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index d6399c0af8..8e77a9de49 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -13,7 +13,8 @@ SYNOPSIS '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 ----------- @@ -78,20 +79,13 @@ be used to detach HEAD at the tip of the branch (`git checkout + Omitting <branch> detaches HEAD at the tip of the current branch. -'git checkout' [-p|--patch] [<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). +'git checkout' [<tree-ish>] [--] <pathspec>...:: + Restore modified or deleted paths in the working tree by + replacing with their original contents from the index, or + the contents from a named <tree-ish> (most often a + commit-ish). 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 @@ specific side of the merge can be checked out of the index by 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. + + OPTIONS ------- -q:: -- 2.15.0-rc0-211-g82b28a23bd
