Subject: Re: [PATCH 2/2] replay: document --update-refs and --batch options

From: Siddharth Asthana <[email-masked]>
Date: Thu, 11 Sep 2025 01:58:25 +0530

On 10/09/25 00:50, Andrei Rybak wrote:
> hello, Siddharth Asthana
>
> On 08/09/2025 06:36, Siddharth Asthana wrote:
>> @@ -91,6 +120,27 @@ $ git replay --advance target origin/main..mybranch
>>   update refs/heads/target ${NEW_target_HASH} ${OLD_target_HASH}
>>   ------------
>>   +To rebase `mybranch` onto `target` and update the ref directly:
>> +
>> +------------
>> +$ git replay --update --onto target origin/main..mybranch
>> +# No output; mybranch is updated directly
>> +------------
>> +
>> +To rebase `mybranch` onto `target` using atomic ref transactions:
>> +
>> +------------
>> +$ git replay --update-refs --onto target origin/main..mybranch
>> +# No output; mybranch is updated atomically
>> +------------
>> +
>> +To rebase multiple branches with partial failure tolerance:
>> +
>> +------------
>> +$ git replay --update-refs --batch --contained --onto origin/main 
>> origin/main..tipbranch
>> +# No output; refs updated in batch mode, warnings for any failures
>> +------------
>> +
>>   Note that the first two examples replay the exact same commits and on
>>   top of the exact same new base, they only differ in that the first
>>   provides instructions to make mybranch point at the new commits and
>

Hi Andrei,

> Adding new examples above this paragraph separates it from the 
> existing examples it refers to.

Good catch. I will restructure the examples section in v2 to maintain 
the logical flow, ensuring the explanatory paragraph stays connected to 
the examples it references.

Since I am moving to a default-behavior approach (atomic ref updates by 
default), the examples will be much simpler anyway:

     # Default behavior (atomic updates)
     git replay --onto target origin/main..mybranch

     # Traditional pipeline output
     git replay --output-commands --onto target origin/main..mybranch | 
git update-ref --stdin

This should make the documentation flow more naturally.

Thanks for the review,
Siddharth