[PATCH] Documentation/checkout: clarify description
- From
Jonathan Nieder <jrnieder@gmail.com>
- Date
- May 30, 2010, 08:41 UTC
- Message-ID
- <20100530084153.GA5447@progeny.tock>
To the first-time reader, it may not be obvious that ‘git checkout’ has two modes, nor that if no branch is specified it will read from the index.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> --- Thanks to neha_ from IRC for pointing this out.
Documentation/git-checkout.txt | 28 +++++++++++++++++----------- 1 files changed, 17 insertions(+), 11 deletions(-)
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 4505eb6..99bd7f2 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -15,26 +15,32 @@ SYNOPSIS DESCRIPTION ----------- +Retrieves files from the index or specified tree and writes them +to the working tree. -When <paths> are not given, this command switches branches by -updating the index, working tree, and HEAD to reflect the specified -branch. +'git checkout' [-b <new branch>] [<branch>]:: + When <paths> are not given, this command switches branches by + updating the index, working tree, and HEAD to reflect the + specified branch. ++ If `-b` is given, a new branch is created and checked out, as if linkgit:git-branch[1] were called; in this case you can use the --track or --no-track options, which will be passed to `git branch`. As a convenience, --track without `-b` implies branch creation; see the description of --track below. -When <paths> or --patch are given, this command 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' [--patch] [<tree-ish>] [--] [<pathspec>...]:: + When <paths> or --patch are given, this command 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. ++ The index may contain unmerged entries after a failed merge. By default, if you try to check out such an entry from the index, the checkout operation will fail and nothing will be checked out.
-- 1.7.1