Re: [PATCH v2 1/2] rebase doc: document rebase.useBuiltin

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

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

> The rebase.useBuiltin variable introduced in 55071ea248 ("rebase:
> start implementing it as a builtin", 2018-08-07) was turned on by
> default in 5541bd5b8f ("rebase: default to using the builtin rebase",
> 2018-08-08), but had no documentation.

I actually thought that everybody understood that this was merely an
aid to be used during the development of the feature and never meant
to be given to the end users.

With my devil's advocate hat on, how much do we trust it as an
escape hatch?  After all, the codepath to hide the "rebase in C"
implementation and use the scripted version were never in 'master'
(or 'next' for that matter) with this variable turned off, so I am
reasonably sure it had no serious exposure to real world usage.

Having said that, assuming that the switching back to scripted
version works correctly and assuming that we want to expose this to
end users, I think the patch text makes sense.

Thanks.

> Let's document it so that users who run into any stability issues with
> the C rewrite know there's an escape hatch[1], and make it clear that
> needing to turn off builtin rebase means you've found a bug in git.
>
> 1. https://public-inbox.org/git/87y39w1wc2.fsf@evledraar.gmail.com/
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
>  Documentation/config/rebase.txt | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
>
> diff --git a/Documentation/config/rebase.txt b/Documentation/config/rebase.txt
> index 42e1ba7575..f079bf6b7e 100644
> --- a/Documentation/config/rebase.txt
> +++ b/Documentation/config/rebase.txt
> @@ -1,3 +1,17 @@
> +rebase.useBuiltin::
> +	Set to `false` to use the legacy shellscript implementation of
> +	linkgit:git-rebase[1]. Is `true` by default, which means use
> +	the built-in rewrite of it in C.
> ++
> +The C rewrite is first included with Git version 2.20. This option
> +serves an an escape hatch to re-enable the legacy version in case any
> +bugs are found in the rewrite. This option and the shellscript version
> +of linkgit:git-rebase[1] will be removed in some future release.
> ++
> +If you find some reason to set this option to `false` other than
> +one-off testing you should report the behavior difference as a bug in
> +git.
> +
>  rebase.stat::
>  	Whether to show a diffstat of what changed upstream since the last
>  	rebase. False by default.