Re: [PATCH] Document `rebase.forkpoint` in rebase man page

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 16, 2021, 21:21 UTC
Message-ID: <xmqqtuikrzca.fsf@gitster.g>
In-Reply-To: <xmqqv930ttkr.fsf@gitster.g>

Junio C Hamano <gitster@pobox.com> writes:

Show 18 quoted lines

> wesley@schwengle.net writes:
>
>> From: Wesley Schwengle <wesley@opperschaap.net>
>>
>> The option exists and the rebase behaviour tricked me into thinking
>> there was a bug with git. This will tell people how they can tweak the
>> default behavior.
>
> This tells readers about almost nothing but your frustration.
>
> We, or anybody who will be reading "git log" in 6 months to improve
> the system, will not need to hear it.  Instead we need to understand
>
> what the real problem is, what was wrong in the behaviour, or what
> the expected behaviour was and why the use of the feature was
> inappropriate in the particular case, without which it is impossible
> to understand why this sentence was added when a future developer
> and documenter tries to improve upon this text.

I misspke a bit here. While hearing only your frustration and nothing else won't help us much, we do need to understand what caused your frustration, to avoid frustrating the next user the same way. All of the "Instead we need to understand ..." are about that.

Show 6 quoted lines

> We often do:
>
>   "See also `rebase.forkpoint` in linkgit:git-config[1]."
>
> (for example, there is a reference to linkgit:githooks[5] in the
> same page).

One reason why you didn't find how to tweak the forkpoint feature, other than giving a command line option to countermand it, is because this link pointing at the list of configurations, where the variable is already described, was missing in the doucmentation for the "rebase" command.

Thanks.