doc: git-checkout: clarify intro

- 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 <[email protected]>

Author: jvns

Documentation/git-checkout.adoc

@@ -20,10 +20,14 @@ 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:
+
+1. **Switch branches**, with `git checkout <branch>`
+2. **Restore a different version of a file**, for example with `git
+   checkout <commit> <filename>` or `git checkout <filename>`
+
+See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.
+Here's a description of all of the modes:
 
 `git checkout [<branch>]`::
 	To prepare for working on _<branch>_, switch to it by updating
@@ -511,14 +515,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 a conflict, you can use the double dash `--` to distinguish
+between branches and files:
+
+* `git checkout <branch> --` will force Git to treat the parameter as a
+  branch name or commit
+* `git checkout -- <pathspec>` will force Git to treat the parameter as
+  a set of file(s)
 
 EXAMPLES
 --------