On Mon, Aug 25, 2025 at 3:09 PM Julia Evans via GitGitGadget
<gitgitgadget@xxxxxxxxx> wrote:
>
> From: Julia Evans <julia@xxxxxxx>
>
> - 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@xxxxxxx>
> ---
> Documentation/git-checkout.adoc | 31 +++++++++++++++++++------------
> 1 file changed, 19 insertions(+), 12 deletions(-)
>
> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
> index 40e02cfd6562..ddda891c0ff7 100644
> --- a/Documentation/git-checkout.adoc
> +++ b/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:
This looks good—I initially scratched my head thinking there were 3
modes, but unifying "update files to match index" and "update files to
match specified tree" is easier to digest in this presentation.
>
> `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)
I think we've dropped the bit about the default interpretation of "git
checkout <something>". Maybe
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.
By default, Git interprets `<something>` as a _<tree-ish>_.
[explain what choosing a tree-ish means for the user?]
[Your notes on disambiguation as before]
?
>
> EXAMPLES
> --------
> --
> gitgitgadget
>
>
--
D. Ben Knoble
