development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-07-16 10:38:05 +00:00
Code Issues Actions 9 Packages Projects Releases Wiki Activity

checkout doc: clarify command line args for "checkout paths" mode

Browse source 
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
Helped-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Junio C Hamano 2017-10-11 11:21:03 +09:00
parent 4010f1d1b7
commit b59698aef3
1 changed files with 16 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
Documentation/git-checkout.txt
View file

@ -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>...::
'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 @@ 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. See below for the description of `--patch` option.
OPTIONS
-------
-q::