[PATCH v2 1/5] doc: git-checkout: clarify intro
From: Julia Evans <julia@jvns.ca>
- Many users do not understand the terms "index" or "pathspec". Clarify
in the intro by using an example, so that users can understand the
basic idea without learning the full definition of "pathspec".
- Use the terminology "Switch" and "Restore" to mirror `git switch`
and `git restore`
- Reference (and clarify) the ARGUMENT DISAMBIGUATION section
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-checkout.adoc | 29 +++++++++++++++++------------
1 file changed, 17 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 40e02cfd65..c86941ad53 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,17 @@ $ 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 switches branches, switches commits, or restores the 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>