From: Siddharth Asthana <siddharthasthana31@gmail•com>
To: Christian Couder <christian.couder@gmail•com>
Cc: git@vger•kernel.org, Junio C Hamano <gitster@pobox•com>,
Karthik Nayak <karthik.188@gmail•com>,
Justin Tobler <jltobler@gmail•com>,
Elijah Newren <newren@gmail•com>, Patrick Steinhardt <ps@pks•im>,
Toon Claes <toon@iotcl•com>, John Cai <johncai86@gmail•com>,
Johannes Schindelin <Johannes.Schindelin@gmx•de>
Subject: Re: [PATCH 2/2] replay: document --update-refs and --batch options
Date: Thu, 11 Sep 2025 01:56:06 +0530 [thread overview]
Message-ID: <58064c0d-1139-4c57-ae34-756e52bf5695@gmail.com> (raw)
In-Reply-To: <CAP8UFD1J8fgjZ+din3P_=FjZZFJ+ocqvwTFjBNjpnhrx6=nMqg@mail.gmail.com>
On 09/09/25 12:56, Christian Couder wrote:
> Hi Siddharth,
>
> On Tue, Sep 9, 2025 at 8:36 AM Siddharth Asthana
> <siddharthasthana31@gmail•com> wrote:
>> On 08/09/25 11:30, Christian Couder wrote:
>>> On Mon, Sep 8, 2025 at 6:36 AM Siddharth Asthana
>>>> 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]?
>> I was trying to provide both simple and advanced modes. --update for
>> users who just want "make it work like piping to git update-ref --stdin"
>> and --update-refs for those who want control over transaction modes. But
>> I see this creates confusion.
>>
>> Would you prefer a single option like --update-refs with an optional
>> mode parameter? Something like --update-refs[=batch] where default is
>> atomic?
> My preference would be something like [--update-atomically |
> --update-batch] first. (Maybe names like `--batch-update` and
> `--atomic-update` are better?)
>
> And then something like --update-iteratively could perhaps be added as
> an alternative, if:
>
> - it works exactly the same as piping to `git update-ref --stdin`, and
> - some users want to use it to blindly replace piping to `git
> update-ref --stdin`, and
> - we document that it is not efficient (compared to
> update-atomically and --update-batch) and should only be used to
> blindly (bug for bug) replace piping to `git update-ref --stdin` when
> performance is not an issue.
>
>>> Also how does this --update-refs option compare to the --update-refs
>>> option in git rebase? Is it working in the same way?
>> No, they are different. git rebase --update-refs updates refs that point
>> to commits being rebased. --update-refs updates the target branches from
>> the replay operation itself. The naming collision is unfortunate should
>> I use a different name?
Hi Christian,
> Yeah, my opinion is that "rebase" and "replay" are commands doing
> similar things, so having an `--update-refs` option in both commands
> is a good thing only if the option has the same purpose in both
> commands. If the purpose is a bit different, I think it's better to
> use different names to avoid confusion.
You make an excellent point about the naming collision. The purposes are
indeed different:
- `git rebase --update-refs` updates refs that point to commits being
rebased
- `git replay --update-refs` (in my patch) updates the target branches
from the replay operation
Since Elijah and Junio have endorsed making ref updates the default
behavior, this actually simplifies our naming significantly. The new
design would be:
- Default: atomic ref updates using transactions (no flag needed)
- `--output-commands`: print update commands for traditional pipeline users
- `--allow-partial`: enable partial failure tolerance when some refs
can't be updated
This completely avoids the rebase naming collision while providing the
atomic transaction behavior that's important for server-side operations
like Gitaly. The default behavior gives us the reliability we need
without any naming confusion.
>
>>>> +--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.
>> That correct --update doesn't use transactions it updates refs one by
>> one like `git update-ref --stdin` does. Should I make this clearer in
>> the documentation?
> Yes, please.
>
>>>> Use with `--batch` to allow partial updates.
>>> What about --update, when should it be used?
>> Good point. My thinking was --update for simple cases where you want the
>> exact same behavior as piping to `git update-ref --stdin` and
>> --update-refs when you want transaction guarantees. But I am starting to
>> think this distinction might be confusing users more than helping them.
>>
>> Would it be cleaner to just have --update-refs with the batch mode
>> option and drop --update entirely? The sequential behavior can be
>> achieved with --update-refs --batch if someone really needs it.
> About the options that should be implemented, see my opinion above.
>
> About possible confusion, I think that to avoid it, it is important to:
>
> - name the options properly (see above what I think about the
> `--update-refs` name), and to
>
> - document thoroughly how all the options differ from each other and
> from piping to `git update-ref --stdin`
>
> Thanks.
Absolutely agree. The simplified approach with default atomic behavior
eliminates most of the confusion points you identified. I will ensure
the documentation clearly explains when users would want
`--output-commands` (for custom scripting) versus the default atomic
behavior (for reliable operations).
The atomic-by-default approach also means better performance since we're
using batched transactions (addressing Patrick's reftable concerns) and
better UX since users get reliable behavior without needing to
understand transaction modes.
Thanks for catching the naming issue christian - it led to a much
cleaner design,
Siddharth
next prev parent reply other threads:[~2025-09-10 20:26 UTC|newest]
Thread overview: 125+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-09-08 4:36 [PATCH 0/2] replay: add --update-refs option Siddharth Asthana
2025-09-08 4:36 ` [PATCH 1/2] " Siddharth Asthana
2025-09-08 9:54 ` Patrick Steinhardt
2025-09-09 6:58 ` Siddharth Asthana
2025-09-09 9:00 ` Patrick Steinhardt
2025-09-09 7:32 ` Elijah Newren
2025-09-10 17:58 ` Siddharth Asthana
2025-09-08 4:36 ` [PATCH 2/2] replay: document --update-refs and --batch options Siddharth Asthana
2025-09-08 6:00 ` Christian Couder
2025-09-09 6:36 ` Siddharth Asthana
2025-09-09 7:26 ` Christian Couder
2025-09-10 20:26 ` Siddharth Asthana [this message]
2025-09-08 14:40 ` Kristoffer Haugsbakk
2025-09-09 7:06 ` Siddharth Asthana
2025-09-09 19:20 ` Andrei Rybak
2025-09-10 20:28 ` Siddharth Asthana
2025-09-08 6:07 ` [PATCH 0/2] replay: add --update-refs option Christian Couder
2025-09-09 6:36 ` Siddharth Asthana
2025-09-08 14:33 ` Kristoffer Haugsbakk
2025-09-09 7:04 ` Siddharth Asthana
2025-09-09 7:13 ` Elijah Newren
2025-09-09 7:47 ` Christian Couder
2025-09-09 9:19 ` Elijah Newren
2025-09-09 16:44 ` Junio C Hamano
2025-09-09 19:52 ` Elijah Newren
2025-09-26 23:08 ` [PATCH v2 0/1] replay: make atomic ref updates the default behavior Siddharth Asthana
2025-09-26 23:08 ` [PATCH v2 1/1] " Siddharth Asthana
2025-09-30 8:23 ` Christian Couder
2025-10-02 22:16 ` Siddharth Asthana
2025-10-03 7:30 ` Christian Couder
2025-10-02 22:55 ` Elijah Newren
2025-10-03 7:05 ` Christian Couder
2025-09-30 10:05 ` Phillip Wood
2025-10-02 10:00 ` Karthik Nayak
2025-10-02 22:20 ` Siddharth Asthana
2025-10-02 22:20 ` Siddharth Asthana
2025-10-08 14:01 ` Phillip Wood
2025-10-08 20:09 ` Siddharth Asthana
2025-10-08 20:59 ` Elijah Newren
2025-10-08 21:16 ` Siddharth Asthana
2025-10-09 9:40 ` Phillip Wood
2025-10-02 16:32 ` Elijah Newren
2025-10-02 18:27 ` Junio C Hamano
2025-10-02 23:42 ` Siddharth Asthana
2025-10-02 23:27 ` Siddharth Asthana
2025-10-03 7:59 ` Christian Couder
2025-10-08 19:59 ` Siddharth Asthana
2025-10-03 19:48 ` Elijah Newren
2025-10-03 20:32 ` Junio C Hamano
2025-10-08 20:06 ` Siddharth Asthana
2025-10-08 20:59 ` Junio C Hamano
2025-10-08 21:10 ` Siddharth Asthana
2025-10-08 21:30 ` Elijah Newren
2025-10-08 20:05 ` Siddharth Asthana
2025-10-02 17:14 ` [PATCH v2 0/1] " Kristoffer Haugsbakk
2025-10-02 23:36 ` Siddharth Asthana
2025-10-03 19:05 ` Kristoffer Haugsbakk
2025-10-08 20:02 ` Siddharth Asthana
2025-10-08 20:56 ` Elijah Newren
2025-10-08 21:16 ` Kristoffer Haugsbakk
2025-10-08 21:18 ` Siddharth Asthana
2025-10-13 18:33 ` [PATCH v3 0/3] replay: make atomic ref updates the default Siddharth Asthana
2025-10-13 18:33 ` [PATCH v3 1/3] replay: use die_for_incompatible_opt2() for option validation Siddharth Asthana
2025-10-13 18:33 ` [PATCH v3 2/3] replay: make atomic ref updates the default behavior Siddharth Asthana
2025-10-13 22:05 ` Junio C Hamano
2025-10-15 5:01 ` Siddharth Asthana
2025-10-13 18:33 ` [PATCH v3 3/3] replay: add replay.defaultAction config option Siddharth Asthana
2025-10-13 19:39 ` [PATCH v3 0/3] replay: make atomic ref updates the default Junio C Hamano
2025-10-15 4:57 ` Siddharth Asthana
2025-10-15 10:33 ` Christian Couder
2025-10-15 14:45 ` Junio C Hamano
2025-10-22 18:50 ` [PATCH v4 " Siddharth Asthana
2025-10-22 18:50 ` [PATCH v4 1/3] replay: use die_for_incompatible_opt2() for option validation Siddharth Asthana
2025-10-22 18:50 ` [PATCH v4 2/3] replay: make atomic ref updates the default behavior Siddharth Asthana
2025-10-22 21:19 ` Junio C Hamano
2025-10-28 19:03 ` Siddharth Asthana
2025-10-24 10:37 ` Christian Couder
2025-10-24 15:23 ` Junio C Hamano
2025-10-28 20:18 ` Siddharth Asthana
2025-10-28 19:39 ` Siddharth Asthana
2025-10-22 18:50 ` [PATCH v4 3/3] replay: add replay.refAction config option Siddharth Asthana
2025-10-24 11:01 ` Christian Couder
2025-10-24 15:30 ` Junio C Hamano
2025-10-28 20:08 ` Siddharth Asthana
2025-10-28 19:26 ` Siddharth Asthana
2025-10-24 13:28 ` Phillip Wood
2025-10-24 13:36 ` Phillip Wood
2025-10-28 19:47 ` Siddharth Asthana
2025-10-28 19:46 ` Siddharth Asthana
2025-10-23 18:47 ` [PATCH v4 0/3] replay: make atomic ref updates the default Junio C Hamano
2025-10-25 16:57 ` Junio C Hamano
2025-10-28 20:19 ` Siddharth Asthana
2025-10-24 9:39 ` Christian Couder
2025-10-28 21:46 ` [PATCH v5 " Siddharth Asthana
2025-10-28 21:46 ` [PATCH v5 1/3] replay: use die_for_incompatible_opt2() for option validation Siddharth Asthana
2025-10-28 21:46 ` [PATCH v5 2/3] replay: make atomic ref updates the default behavior Siddharth Asthana
2025-10-28 21:46 ` [PATCH v5 3/3] replay: add replay.refAction config option Siddharth Asthana
2025-10-29 16:19 ` Christian Couder
2025-10-29 17:00 ` Siddharth Asthana
2025-10-30 19:19 ` [PATCH v6 0/3] replay: make atomic ref updates the default Siddharth Asthana
2025-10-30 19:19 ` [PATCH v6 1/3] replay: use die_for_incompatible_opt2() for option validation Siddharth Asthana
2025-10-31 18:47 ` Elijah Newren
2025-11-05 18:39 ` Siddharth Asthana
2025-10-30 19:19 ` [PATCH v6 2/3] replay: make atomic ref updates the default behavior Siddharth Asthana
2025-10-31 18:49 ` Elijah Newren
2025-10-31 19:59 ` Junio C Hamano
2025-11-05 19:07 ` Siddharth Asthana
2025-11-03 16:25 ` Phillip Wood
2025-11-03 19:32 ` Siddharth Asthana
2025-11-04 16:15 ` Phillip Wood
2025-10-30 19:19 ` [PATCH v6 3/3] replay: add replay.refAction config option Siddharth Asthana
2025-10-31 7:08 ` Christian Couder
2025-11-05 19:03 ` Siddharth Asthana
2025-10-31 18:49 ` Elijah Newren
2025-11-05 19:10 ` Siddharth Asthana
2025-10-31 18:51 ` [PATCH v6 0/3] replay: make atomic ref updates the default Elijah Newren
2025-11-05 19:15 ` [PATCH v7 " Siddharth Asthana
2025-11-05 19:15 ` [PATCH v7 1/3] replay: use die_for_incompatible_opt2() for option validation Siddharth Asthana
2025-11-05 19:16 ` [PATCH v7 2/3] replay: make atomic ref updates the default behavior Siddharth Asthana
2025-11-05 19:16 ` [PATCH v7 3/3] replay: add replay.refAction config option Siddharth Asthana
2025-11-06 19:32 ` [PATCH v7 0/3] replay: make atomic ref updates the default Elijah Newren
2025-11-08 13:22 ` Siddharth Asthana
2025-11-08 17:11 ` Elijah Newren
2025-11-07 15:48 ` Phillip Wood
2025-11-08 13:23 ` Siddharth Asthana
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=58064c0d-1139-4c57-ae34-756e52bf5695@gmail.com \
--to=siddharthasthana31@gmail$(echo .)com \
--cc=Johannes.Schindelin@gmx$(echo .)de \
--cc=christian.couder@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=jltobler@gmail$(echo .)com \
--cc=johncai86@gmail$(echo .)com \
--cc=karthik.188@gmail$(echo .)com \
--cc=newren@gmail$(echo .)com \
--cc=ps@pks$(echo .)im \
--cc=toon@iotcl$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox