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

From: Junio C Hamano <[email-masked]>
Date: Thu, 16 Sep 2021 08:43:00 -0700

[email-masked] writes:

> From: Wesley Schwengle <[email-masked]>
>
> 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.

> Signed-off-by: Wesley Schwengle <[email-masked]>
> ---
>  Documentation/git-rebase.txt | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
> index 506345cb0e..8d2bee3365 100644
> --- a/Documentation/git-rebase.txt
> +++ b/Documentation/git-rebase.txt
> @@ -446,7 +446,8 @@ When --fork-point is active, 'fork_point' will be used instead of
>  ends up being empty, the <upstream> will be used as a fallback.
>  +
>  If <upstream> is given on the command line, then the default is
> -`--no-fork-point`, otherwise the default is `--fork-point`.
> +`--no-fork-point`, otherwise the default is `--fork-point`. You can override
> +this default by setting the configuration option `rebase.forkpoint` to false.

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

Thanks.