Re: [PATCH] doc: explain the impact of stash.index on --autostash options

From: D. Ben Knoble <ben.knoble+github@gmail.com>
Date: Oct 11, 2025, 14:44 UTC
Message-ID: <CALnO6CA0SEGrzsrS_yqZ3Ztep0Gi=zPFjjGzSW94EvDW8RZ2Bg@mail.gmail.com>
In-Reply-To: <e77d07d0-c26e-4d91-9777-ebaffffd764c@app.fastmail.com>

On Thu, Oct 9, 2025 at 6:55 PM Kristoffer Haugsbakk <code@khaugsbakk.name> wrote:

Show 16 quoted lines

>
> This follow-up patch makes sense.
>
> • It reads like a logical continuation of the previous commit 9842c0c749
> • The log message is clear (and with no spelling mistakes)
> • The markup is correct (list continuation, links)
> • `make lint-docs` passes
> • `./ci/check-whitespace.sh @^` passes
>
> On Mon, Oct 6, 2025, at 14:59, D. Ben Knoble wrote:
> > With 9842c0c749 (stash: honor stash.index in apply, pop modes,
> > 2025-09-21)
>
> Curiously, since this is also the base commit, referring to “the
> previous commit” would also work if this patch is indeed applied on top
> of that one. But maybe that contextual reference is a bad idea?

Generally I think so, but that's just my preference. Once commits have stable reference points, I'd rather use that. But I'm not attached to this one, so if we end up re-rolling, I can adjust either way.

Show 9 quoted lines

> > merged in a5d4779e6e (Merge branch 'dk/stash-apply-index',
> > 2025-09-29),
>
> This is over-specified IMO. Like mentioned this patch could be applied
> on top of commit 9842c0c749. Then that merge commit will not be
> reachable from this resulting commit.
>
> I also don’t see the point of mentioning when things were merged in in
> the commit message.

Indeed. I think I wanted to call out the topic branch this was part of, especially since my understanding of the process of queueing patches on top of in-flight topics is shaky from parts of Documentation/SubmittingPatches and …/howto/maintain-git:

 * A topic already in 'next' can get fixes while still in
   'next'.  Such a topic will have many merges to 'next' (in
   other words, "git log --first-parent next" will show many
   "Merge branch 'ai/topic' to next" for the same topic.

So, idk. If the eventual merge to master won't have the prior "topic merge," it's probably important to omit (since the final topology of master won't contain the referenced commit). In this case, since that merge _is_ part of master, it seemed worth explaining what topic we were improving.

Show 22 quoted lines

> > diff --git a/Documentation/config/stash.adoc b/Documentation/config/stash.adoc
> > index e556105a15..fcb9a4a7a0 100644
> > --- a/Documentation/config/stash.adoc
> > +++ b/Documentation/config/stash.adoc
> > @@ -2,6 +2,10 @@ stash.index::
> >       If this is set to true, `git stash apply` and `git stash pop` will
> >       behave as if `--index` was supplied. Defaults to false. See the
> >       descriptions in linkgit:git-stash[1].
> > ++
> > +This also affects invocations of linkgit:git-stash[1] via `--autostash` from
> > +commands like linkgit:git-merge[1], linkgit:git-rebase[1], and
> > +linkgit:git-pull[1].
>
> According to these
>
> • `git grep -- --autostash`
> • `git grep merge-options.adoc`
>
> This text exhaustively covers all commands which have this option.
>
> ... which might mean that “like” is an unneeded hedge? (it’s probably
> not intended to be a hedge)

Indeed. I'm not sure where autostash might be introduced in the future (git-history?), so it might be more "hedge" by way of "listing examples" than necessary.

I could go either way on all of this, so will defer to guidance from others (but don't have the impetus to rewrite without a strong opinion at the moment).