[PATCH v3 1/6] doc: git-checkout: clarify intro
From: Julia Evans <julia@jvns.ca>
- Reduce use of jargon ("index", "pathspec", "tree") by using an
example, and by mirroring the "switch" and "restore" language from the
first line of the man page.
- Reference and clarify the ARGUMENT DISAMBIGUATION section, as well
as fixing a small error (in "`git checkout abc`, `abc` is a commit,
not a `_<tree-ish>_`)Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-checkout.adoc | 30 ++++++++++++++++++------------
1 file changed, 18 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 40e02cfd65..218d3dd13d 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -20,10 +20,12 @@ git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
DESCRIPTION
-----------
-Updates files in the working tree to match the version in the index
-or the specified tree. If no pathspec was given, `git checkout` will
-also update `HEAD` to set the specified branch as the current
-branch.
+`git checkout` has two main modes: it can
+**switch branches**, for example with `git checkout <branch>`, and
+**restore files from a different version**, for example with
+`git checkout <commit> <filename>` or `git checkout <filename>`
+
+See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.
`git checkout [<branch>]`::
To prepare for working on _<branch>_, switch to it by updating
@@ -511,14 +513,18 @@ $ git log -g -2 HEAD
ARGUMENT DISAMBIGUATION
-----------------------
-When there is only one argument given and it is not `--` (e.g. `git
-checkout abc`), and when the argument is both a valid _<tree-ish>_
-(e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file
-or a directory whose name is "abc" exists), Git would usually ask
-you to disambiguate. Because checking out a branch is so common an
-operation, however, `git checkout abc` takes "abc" as a _<tree-ish>_
-in such a situation. Use `git checkout -- <pathspec>` if you want
-to checkout these paths out of the index.
+When you run `git checkout <something>`, Git tries to guess whether
+`<something>` is intended to be a branch, a commit, or a set of file(s),
+and then either switches to that branch or commit or restores the
+specified files.
+
+If there's any ambiguity, Git will treat `<something>` as a branch or
+commit, but you can use the double dash `--` to force Git to treat the
+parameter as a list of files and/or directories, like this:
+
+----------
+git checkout -- file.txt
+----------
EXAMPLES
--------
--
gitgitgadget
Julia Evans via GitGitGadget <gitgitgadget@gmail.com>