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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 11, 2025, 17:28 UTC
Message-ID: <xmqqy0ph5ov8.fsf@gitster.g>
In-Reply-To: <CALnO6CA0SEGrzsrS_yqZ3Ztep0Gi=zPFjjGzSW94EvDW8RZ2Bg@mail.gmail.com>

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

Show 21 quoted lines

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

Show 6 quoted lines

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

Show 17 quoted lines

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