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

From: Julia Evans <julia@jvns.ca>
Date: Sep 12, 2025, 14:05 UTC
Message-ID: <236a79f4-e9a2-4335-bbff-79ae0cc67e9b@app.fastmail.com>
In-Reply-To: <1629C205-700F-4A8A-84BE-302D172416F8@gmail.com>

Show 9 quoted lines

>> * 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? :)

This one took a few hours because I had to backfill all of the "Changes in v2...", "Changes in v3..." but I think future ones will be faster to write.

Re the convention not being spelled out: in the "my first contribution" guide, it says:

> Edit your cover letter again. Now is a good time to mention what's different
> between your last version and now, if it's something significant. You do not
> need the exact same body in your second cover letter; focus on explaining to
> reviewers the changes you've made that may not be as visible.

The key elements that I was missing from this were:

1. it's actually probably good to keep some (most?) of the body from your original
  cover letter, so that folks don't have to go back to remember what this is about
2. It's useful to flag which review comments you addressed and which you didn't,
  and why, not just what the changes you made are

(I might have gotten those 2 points wrong though!)

Show 16 quoted lines

>>     +    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…”

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.