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

From: "Kristoffer Haugsbakk" <[email-masked]>
Date: Fri, 12 Sep 2025 16:26:36 +0200

On Fri, Sep 12, 2025, at 16:05, Julia Evans wrote:
>> 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…”
>
> Sorry for not mentioning that. My idea was to just leave <pathspec> in the
> synopsis, and then folks can look it up in the glossary if they're curious.
>
> In the web documentation (https://git-scm.com/docs/git-checkout), the word
> "pathspec" is underlined, and hovering over it will show the definition, which
> I think will help with discoverability. Of course in the terminal version of the
> man pages it's harder to build in affordances like that.
>
> Do you think that the concept of a "pathspec" is especially useful/powerful
> in the case of `git checkout`? If we're thinking more globally, i wonder if we
> could find a Git command where more complex pathspecs are especiallly
> useful and then include some examples of using a complex pathspec there.
>
> If we include a compelling example and then a "see X for more about..." (here or
> somewhere else) I think it would be much more likely to motivate users to follow
> the breadcrumbs to learn more.

I think pathspecs are great for git-grep(1).

    # Docs but ignore release notes
    git grep loop -- Documentation/ ':^Documentation/RelNotes'
    # Just the git(1) manuals (more or less)
    git grep loop -- 'Documentation/git-*adoc'

And also for narrowing a git-diff(1), like ignoring `pom.xml` changes in
a Java project.

(But I never got into the habit of using them with git-checkout(1))

But once you learn about them you indeed can find uses for them in a lot
of corners.  I used them today and yesterday to selectively git-clean(1)
and git-rm(1).

There should be a gitpathspecs(7).  Not just a glossary entry.