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

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Sep 12, 2025, 14:26 UTC
Message-ID: <35faaf30-6326-4784-80ff-723c20ed6b13@app.fastmail.com>
In-Reply-To: <236a79f4-e9a2-4335-bbff-79ae0cc67e9b@app.fastmail.com>

On Fri, Sep 12, 2025, at 16:05, Julia Evans wrote:

Show 21 quoted lines

>> 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.