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.
