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

[Junio C Hamano <gitster@pobox.com>]

"D. Ben Knoble" <ben.knoble+github@gmail.com> writes:

> On Thu, Oct 9, 2025 at 6:55 PM Kristoffer Haugsbakk
> <code@khaugsbakk.name> wrote:
>>
>> 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.

That matches my preference, too.  Use of relative "previous" or
"next", unless they are in the same series, can make things
confusing.

For example, you could say something silly like "The test added in
the previous commit revealed age-old bug.  Here is a fix and more
test", and the fix may be important enough that it wants to be
forked from a maintenance track that is far older than the "previous"
commit.

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

Yeah, that is less useful to me (there is a tool, given a commit
object, to figure out at which merge it got merged to the mainline);
I didn't think of a way the information can be useful to general
readers.  If the mainline merge was a release or more ago, then it
may make sense to say "commit X, which appeared in version Y, was
broken in such and such way, and here is to fix its breakage".

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

You have to devise a way to somehow ensure that a list, which
happens to be exhaustive right now, stays exhaustive, if you present
it as authoritative exhaustive list to your readers.  But as long as
the list covers the use cases majority of readers would encounter
every day, it does not make the list any less useful even if it were
not exhausitive (and does not pretend to be).

So I prefer to keep the presented text than making it sound an
authoritative exhaustive list and add maintenance cost.

Thanks.