Re: [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section

From: Ben Knoble <ben.knoble@gmail.com>
Date: Sep 11, 2025, 13:01 UTC
Message-ID: <1629C205-700F-4A8A-84BE-302D172416F8@gmail.com>
In-Reply-To: <pull.1962.v4.git.1757531669.gitgitgadget@gmail.com>

Show 42 quoted lines

> Le 10 sept. 2025 à 15:14, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> a écrit :
> 
> I got feedback from 22 existing Git users on the existing git checkout man
> page, using this tool: https://text-feedback.wizardzines.com/git-checkout.
> From a short survey they filled out, about 90% of the users who gave the
> feedback have 5+ years of experience using Git.
> 
> This series goes through the DESCRIPTION section from beginning to end,
> addressing points that users found confusing in each variant of git
> checkout. The goal is to clarify while communicating the same information.
> 
> Changes in v2:
> 
> * Remove the numbered list from the beginning, from Junio's review
> * Describe what it means to "switch branches" in a way that's hopefully
>   more accessible to newcomers, from Junio's review
> * Improve the ARGUMENT DISAMBIGUATION section, from Junio and Ben's reviews
>   ("conflict" => "ambiguity", explain correctly what the default is)
> * The explanation of git checkout [<tree-ish>] <pathspec> had a lot of
>   issues, from Junio's review. Resolve this by splitting up the git
>   checkout [] section into two sections. Use "Replace" instead of
>   "Restore".
> 
> Changes in v3:
> 
> * Fix incorrect description of when git checkout <branch>, from Junio's
>   review
> * Take a different approach to the git checkout -b description (keep reset
>   in -B, but simplify the description of -B a lot to remove the
>   "transactional equivalent.." paragraph), from Junio's review
> * Say "switch to the commit" instead of "switches commits", from Junio's
>   review
> * Try a different approach to git checkout file.txt ("Discard any unstaged
>   changes...")
> 
> Changes in v4:
> 
> * Rewrite all the commit messages to try to take a more Problem / Solution
>   approach, from Junio's review and thanks to help from @nasamuffin in
>   Discord. Also change the cover letter format to match the style in
>   https://lore.kernel.org/git/CAOLa=ZStgwBN0fMK3YxoqeR+1i772f621supva3Kvr7YPq4g8g@mail.gmail.com/T/#m8c99a3144cbdfb445e04f8f83a79364bfe8d797d
>   , which hopefully matches the norms of this mailing list better.

This was pleasant reading to me. Not sure how it felt for you to write? Or if the convention was just not spelled out enough to get you where you wanted to be? :)

Show 33 quoted lines

> * Try a different approach to the "left unchanged...", from Junio's review
> * Bring back "index" (with a few hints about what the word might mean),
>   from Junio's review.
> * Bring back the numbered list at the beginning from v1, since I think I
>   misunderstood a comment about lists, and that the original was clearer
> * Fix an issue I noticed in -B ("instead of failing", not "instead of
>   creating it")
> * Add a comma after branch or commit, to try to make it clear what "either"
>   refers to in that sentence
> * Replace "will fail without making any changes" throughout with just "will
>   fail". I think the default assumption is that Git will fail operations in
>   a clean way, and that cases where it does not fail cleanly are the
>   exceptions that the documentation should flag.
> 
> Julia Evans (7):
>  doc: git-checkout: clarify intro sentence
>  doc: git-checkout: clarify ARGUMENT DISAMBIGUATION
>  doc: git-checkout: clarify `git checkout <branch>`
>  doc: git-checkout: clarify `-b` and `-B`
>  doc: git-checkout: deduplicate --detach explanation
>  doc: git-checkout: split up restoring files section
>  doc: git-checkout: clarify restoring files section
> 
> Documentation/git-checkout.adoc | 151 ++++++++++++++++----------------
> 1 file changed, 76 insertions(+), 75 deletions(-)
> 
> 
> base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1962%2Fjvns%2Fclarify-checkout-v4
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1962/jvns/clarify-checkout-v4
> Pull-Request: https://github.com/gitgitgadget/git/pull/1962
> 
> Range-diff vs v3:

Range-diff looks good to me!

Show 67 quoted lines

> 
> -:  ---------- > 1:  4b52ffd497 doc: git-checkout: clarify intro sentence
> 1:  1975384dd0 ! 2:  08f0a5efab doc: git-checkout: clarify intro
>     @@ Metadata
>      Author: Julia Evans <julia@jvns.ca>
> 
>       ## Commit message ##
>     -    doc: git-checkout: clarify intro
>     +    doc: git-checkout: clarify ARGUMENT DISAMBIGUATION
> 
>     -    - 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>_`)
>     +    There's no need to use the terms "pathspec" or "tree-ish" in the
>     +    ARGUMENT DISAMBIGUATION section, which are terms that (from user
>     +    feedback on this page) many users do not understand.
>     +
>     +    "tree-ish" is actually not accurate here: `git checkout` in this case
>     +    takes a commit-ish, not a tree-ish. So we can say "branch or commit"
>     +    instead of "tree-ish" which is both more accurate and uses more familiar
>     +    terms.
>     +
>     +    And now that the intro to the man pages mentions that `git checkout` has
>     +    "two main modes", it makes sense to refer to this disambiguation section
>     +    to understand how Git decides which one to use when there's an overlap
>     +    in syntax.
> 
>          Signed-off-by: Julia Evans <julia@jvns.ca>
> 
>       ## Documentation/git-checkout.adoc ##
>     -@@ Documentation/git-checkout.adoc: git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
>     +@@ Documentation/git-checkout.adoc: DESCRIPTION
>     + 2. **Restore a different version of a file**, for example with
>     +    `git checkout <commit> <filename>` or `git checkout <filename>`
> 
>     - 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
>     +    the index and the files in the working tree, and by pointing
>      @@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD
>       ARGUMENT DISAMBIGUATION
>       -----------------------
>     @@ Documentation/git-checkout.adoc: $ git log -g -2 HEAD
>      -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
>     ++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

Show 23 quoted lines

> 6:  90fe48cfe3 ! 7:  db603b1e5f doc: git-checkout: clarify restoring files section
>     @@ Metadata
>       ## Commit message ##
>          doc: git-checkout: clarify restoring files section
> 
>     -    - Reword to avoid jargon ("tree-ish", "index") where possible.
>     -      Use "commit or tree" and "stage" (as a verb) instead where appropriate
>     -    - Add examples
>     -    - Use a simpler sentence structure to describe options for handling
>     -      unmerged entries: "use -f to.., use --ours to..., or use -m to.."
>     +    From user feedback on this section: 3 users don't know what "tree-ish"
>     +    means and 3 users don't know what "pathspec" means. One user also says
>     +    that the section is very confusing and that they don't understand what
>     +    the "index" is.
>     +
>     +    From conversations on Mastodon, several users said that their impression
>     +    is that "the index" means the same thing as "HEAD". It would be good to
>     +    give those users (and other users who do not know what "index" means) a
>     +    hint as to its meaning.
>     +
>     +    Make this section more accessible to users who don't know what the terms
>     +    "pathspec", "tree-ish", and "index" mean by using more familiar language,
>     +    adding examples, and using simpler sentence structures.

Without re-examining the individual patches, I see that 2/7 and 7/7 (possibly also new 1/7) lost pointers to pathspecs. I think I mentioned this previously: I hope we can find some way to direct folks towards the glossary entries that describe them. I would consider pathspecs a power-user feature, and they create lots of useful affordances. So it is fair to more gently introduce newcomers, but I would also still like to make sure it clear when commands accept pathspec “magic” :)

OTOH, I’ll take a look at the docs after this series lands and see if it feels like something is missing. It may be just fine to have pathspecs in the synopses and add a sentence somewhere after the gentle introduction “For more ways to specify paths, see…”