From: Siddharth Asthana <siddharthasthana31@gmail.com>
Date: Wed, 15 Oct 2025 05:05:02 GMT
Subject: Re: [PATCH v3 0/3] replay: make atomic ref updates the default
Message-ID: <92f9bdec-28ba-45ba-a111-24963d0a300a@gmail.com>
In-Reply-To: <xmqqtt01w5jh.fsf@gitster.g>


On 15/10/25 02:43, Junio C Hamano wrote:
> When merged to 'seen', this breaks t0450; from the way the test
> breaks, I suspect that it has the same breakage if the topic gets
> tested standalone.
>
>      $ make
>      $ cd t
>      $ sh t0450-txt-doc-vs-help.sh -i -v
>      ...
>      --- adoc        2025-10-14 21:02:48.680184914 +0000
>      +++ help        2025-10-14 21:02:48.688184867 +0000
>      @@ -1,2 +1 @@
>      -(EXPERIMENTAL!) git replay ([--contained] --onto <newbase> | --advance <branch>)
>      -           [--update-refs[=<mode>]] <revision-range>...
>      +(EXPERIMENTAL!) git replay ([--contained] --onto <newbase> | --advance <branch>) [--update-refs[=<mode>]] <revision-range>...
>      not ok ...
>
> In short, "git replay -h" and the initial part of "git replay --help"
> must match.


Thanks for catching this! I actually noticed the CI was failing on 
documentation
checks while testing on GitLab before sending v3 to the list. I 
initially thought
it was an AsciiDoc line continuation issue and suggested adding a `+` at 
the end
of the line, but Christian pointed out that the real issue was likely 
the mismatch
between the synopsis and the help output from the command itself.

I split the SYNOPSIS across two lines in the documentation for readability:

     (EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | 
--advance <branch>)
             [--update-refs[=<mode>]] <revision-range>...

But didn't update the usage string in builtin/replay.c to match. Your 
patch adding
"\n" and the proper indentation is exactly what's needed:

     "(EXPERIMENTAL!) git replay ([--contained] --onto <newbase> | 
--advance <branch>)\n"
     "\t\t[--update-refs[=<mode>]] <revision-range>..."

I will squash this into the next version. I should have run t0450 
locally after
Christian's hint about the synopsis check - I was focused on t3650 and the
functional tests but missed this formatting requirement.

Thanks,
Siddharth


>
> Minimally you'd need to squash in something like the following
> patch.  Alternatively, you could match the documentation page (which
> is shown by "git replay --help") to match what "git replay -h" gives.
>
>
>   builtin/replay.c | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git i/builtin/replay.c w/builtin/replay.c
> index 3c618bf100..d0f0492790 100644
> --- i/builtin/replay.c
> +++ w/builtin/replay.c
> @@ -330,7 +330,7 @@ int cmd_replay(int argc,
>   
>   	const char *const replay_usage[] = {
>   		N_("(EXPERIMENTAL!) git replay "
> -		   "([--contained] --onto <newbase> | --advance <branch>) "
> +		   "([--contained] --onto <newbase> | --advance <branch>)\n"
>   		   "[--update-refs[=<mode>]] <revision-range>..."),
>   		NULL
>   	};