Document `rebase.forkpoint` in rebase man page

Commit Message

Wesley Schwengle Sept. 16, 2021, 10:35 p.m. UTC

From: Wesley Schwengle <[e-mail]>

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.

Signed-off-by: Wesley Schwengle <[e-mail]>
---
 Documentation/git-rebase.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

Comments

Junio C Hamano Sept. 16, 2021, 10:47 p.m. UTC | #1

[e-mail] writes:

> From: Wesley Schwengle <[e-mail]>
>
> 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.

So this still does not explain what rebase behaviour tricked you
into thinking so.  That leaves the readers of "git log" frustrated,
much more than a log message based only on a simple statement of
fact, e.g.

    "git config --help" describes rebase.forkpoint as a way to give
    the default value for --[no-]forkpoint option, but "git rebase
    --help" does not mention it.  

    Help people who visits the documentation of "rebase" to find the
    variable.

or something like that.

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

It is not wrong per-se, but sounds overly verbose and seems to give
only half an advice.  You can also set it to 'true' to override the
default --no-fork-point given when you give <upstream> on the
command line, no?  So perhaps only a single line addition (plus
downcasing "If" to "if"), i.e.

+   If `rebase.forkpoint` is set, that gives the default.  Otherwise,
    if <upstream is given on the command line, the default is ...

would be a better rewrite?

Thanks.

Wesley Schwengle Sept. 16, 2021, 10:50 p.m. UTC | #2

On 9/16/21 6:47 PM, Junio C Hamano wrote:
> [e-mail] writes:
> 
>> From: Wesley Schwengle <[e-mail]>
>>
>> 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.
> 
> So this still does not explain what rebase behaviour tricked you
> into thinking so.  That leaves the readers of "git log" frustrated,
> much more than a log message based only on a simple statement of
> fact, e.g.
> 
>      "git config --help" describes rebase.forkpoint as a way to give
>      the default value for --[no-]forkpoint option, but "git rebase
>      --help" does not mention it.
> 
>      Help people who visits the documentation of "rebase" to find the
>      variable.
> 
> or something like that.

I made a booboo. I did not run format-patch with the updated commit 
message and commit. I saw it too late. You should have a new one by the 
time you read this :)

Cheers,
Wesley

Junio C Hamano Sept. 16, 2021, 10:53 p.m. UTC | #3

Wesley Schwengle <[e-mail]> writes:

> I made a booboo. I did not run format-patch with the updated commit
> message and commit. I saw it too late. You should have a new one by

That is OK.  Mistakes happen.

I'll slow down to avoid further confusion from mails crossing, but I
have a feeling that you either forgot to read, or sent an updated
patch before reading, the latter half of the message you are
responding to.

Thanks.

Wesley Schwengle Sept. 20, 2021, 2:34 p.m. UTC | #4

On 9/16/21 6:53 PM, Junio C Hamano wrote:
> Wesley Schwengle <[e-mail]> writes:
> 
>> I made a booboo. I did not run format-patch with the updated commit
>> message and commit. I saw it too late. You should have a new one by
> 
> That is OK.  Mistakes happen.
> 
> I'll slow down to avoid further confusion from mails crossing, but I
> have a feeling that you either forgot to read, or sent an updated
> patch before reading, the latter half of the message you are
> responding to.

I did the same thing, the patch is present in the thread at 
https://public-inbox.org/git/[e-mail]/

Cheers,
Wesley

Patch

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.
 +
 If your branch was based on <upstream> but <upstream> was rewound and
 your branch contains commits which were dropped, this option can be used