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

From: Christian Couder <christian.couder@gmail.com>
Date: Sep 8, 2025, 06:00 UTC
Message-ID: <CAP8UFD3Db-n3CY=KBpn-2Nt=SYY=5ckF3J_4ho6C19SVcrfdsQ@mail.gmail.com>
In-Reply-To: <20250908043620.57848-3-siddharthasthana31@gmail.com>

On Mon, Sep 8, 2025 at 6:36 AM Siddharth Asthana <siddharthasthana31@gmail.com> 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?

Show 15 quoted lines

> Signed-off-by: Siddharth Asthana <siddharthasthana31@gmail.com>
> ---
>  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 <newbase> | --advance <branch>) <revision-range>...
> +(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch>) [--update | --update-refs [--batch]] <revision-range>...

Here --update, --update-refs and --batch are all documented, nice.

Show 12 quoted lines

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

Show 10 quoted lines

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

Show 22 quoted lines

>  <revision-range>::
>         Range of commits to replay. More than one <revision-range> can
>         be passed, but in `--advance <branch>` 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.