From: Christian Couder Date: Mon, 08 Sep 2025 06:00:44 GMT Subject: Re: [PATCH 2/2] replay: document --update-refs and --batch options Message-ID: In-Reply-To: <20250908043620.57848-3-siddharthasthana31@gmail.com> On Mon, Sep 8, 2025 at 6:36 AM Siddharth Asthana wrote: > > Add documentation for the new --update-refs option which performs > ref updates directly using Git's ref transaction API, eliminating > the need for users to pipe output to git update-ref --stdin. Most of the time, the documentation should be part of the patch that introduces the documented behavior, not in a separate patch. > Also document the --batch option which can be used with --update-refs > to allow partial failures in ref updates. It looks like a --update option was also added by the previous patch. Is it documented here too? Why was this [--update | --update-refs [--batch]] set of options selected over other possibilities like for example [--update-iteratively | --update-atomically | --update-batch]? Also how does this --update-refs option compare to the --update-refs option in git rebase? Is it working in the same way? > Signed-off-by: Siddharth Asthana > --- > Documentation/git-replay.adoc | 62 +++++++++++++++++++++++++++++++---- > 1 file changed, 56 insertions(+), 6 deletions(-) > > diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc > index 0b12bf8aa4..cc9f868c2f 100644 > --- a/Documentation/git-replay.adoc > +++ b/Documentation/git-replay.adoc > @@ -9,16 +9,17 @@ git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos t > SYNOPSIS > -------- > [verse] > -(EXPERIMENTAL!) 'git replay' ([--contained] --onto | --advance ) ... > +(EXPERIMENTAL!) 'git replay' ([--contained] --onto | --advance ) [--update | --update-refs [--batch]] ... Here --update, --update-refs and --batch are all documented, nice. > DESCRIPTION > ----------- > > Takes ranges of commits and replays them onto a new location. Leaves > -the working tree and the index untouched, and updates no references. > -The output of this command is meant to be used as input to > +the working tree and the index untouched, and by default updates no > +references. The output of this command is meant to be used as input to > `git update-ref --stdin`, which would update the relevant branches > -(see the OUTPUT section below). > +(see the OUTPUT section below). Alternatively, with `--update`, the > +refs can be updated directly. Here only --update is documented. > THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. > > @@ -42,6 +43,24 @@ When `--advance` is specified, the update-ref command(s) in the output > will update the branch passed as an argument to `--advance` to point at > the new commits (in other words, this mimics a cherry-pick operation). > > +--update:: > + Update the relevant refs directly instead of outputting > + update-ref commands. When this option is used, no output is > + produced on successful completion, It seems a bit redundant to say both "instead of outputting update-ref commands" and then "no output is produced on successful completion". Maybe there is a way to reword this to be a bit more concise. > and the refs are updated > + immediately. If any ref update fails, the command will exit > + with a non-zero status. This doesn't say if the command immediately stops when it fails to update a ref, and if the ref updates are atomic or not. > +--update-refs:: > + Update the relevant refs using ref transactions instead of outputting > + update-ref commands. By default, uses atomic mode where all ref updates > + succeed or all fail. This seems to imply that --update doesn't update the refs atomically. > Use with `--batch` to allow partial updates. What about --update, when should it be used? > + When this option is used, no output is produced on successful completion. Here also it seems a bit redundant to say both "instead of outputting update-ref commands" and then "no output is produced on successful completion". And maybe there is a way to reword this to be a bit more concise. > +--batch:: > + Can only be used with `--update-refs`. Enables batch mode for ref > + updates, allowing some refs to be updated successfully even if others > + fail. Failed updates are reported as warnings rather than errors. What's the difference with --update? Is it that --update immediately stops when a ref update fails? > :: > Range of commits to replay. More than one can > be passed, but in `--advance ` mode, they should have > @@ -54,8 +73,9 @@ include::rev-list-options.adoc[] > OUTPUT > ------ > > -When there are no conflicts, the output of this command is usable as > -input to `git update-ref --stdin`. It is of the form: > +When there are no conflicts and neither `--update` nor `--update-refs` > +is used, the output of this command is usable as input to `git update-ref --stdin`. > +It is of the form: > > update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH} > update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH} > @@ -66,6 +86,15 @@ the shape of the history being replayed. When using `--advance`, the > number of refs updated is always one, but for `--onto`, it can be one > or more (rebasing multiple branches simultaneously is supported). > > +When `--update` is used, no output is produced and the refs are updated > +directly using individual ref updates. This is equivalent to piping the normal output to > +`git update-ref --stdin`. Is it equivalent to `git update-ref --stdin` because both exit as soon as a ref update fails? > +When `--update-refs` is used, no output is produced and the refs are updated > +using ref transactions. In atomic mode (default), all ref updates succeed > +or all fail. In batch mode (with `--batch`), some updates may succeed while > +others fail, with failed updates reported as warnings.