[PATCH 0/1] Add "preparing" phase to reference-transaction hook

From: Eric Ju <eric.peijian@gmail.com>

The "reference-transaction" hook currently exposes three phases to callers: "prepared", "committed", and "aborted". The earliest of these, "prepared", fires after Git has already acquired exclusive locks on every affected reference. This is well-suited for last-chance validation, but it arrives too late for any use case that requires coordination before locking, such as serializing concurrent transactions across distributed storage nodes.

This series introduces a new "preparing" phase that fires before refs->be->transaction_prepare() is called, that is, before Git takes any reference lock on disk. Hook scripts that handle this phase receive the full list of proposed updates and may reject the transaction by returning a non-zero exit status, causing Git to abort cleanly before any locks are acquired.

The motivating use case is Gitaly/Praefect, GitLab's distributed Git storage layer. Praefect must serialize concurrent writes that target the same references across replicas. With only the "prepared" phase available, by the time Praefect can observe a transaction the locks are already held, making reordering impossible. The "preparing" phase provides the necessary pre-lock window.

Compatibility note: this change is not strictly backwards compatible. Hook scripts that do not expect unknown phase strings may return an error when they encounter "preparing". We consider this acceptable for the same reasons cited when symref support was added to the hook in a8ae923f85 (refs: support symrefs in 'reference-transaction' hook, 2024-05-07): the hook is documented as exposing internal implementation details, and its semantics have been adjusted before. An alternative of introducing a "reference-transaction-v2" hook was considered but rejected as unnecessarily heavyweight.

Eric Ju (1):
  Add preparing state to reference-transaction hook

 Documentation/githooks.adoc      | 19 ++++++++++++-------
 refs.c                           |  9 ++++++++-
 t/t1416-ref-transaction-hooks.sh | 30 ++++++++++++++++++++++++++----
 t/t5510-fetch.sh                 |  7 ++++++-
 4 files changed, 52 insertions(+), 13 deletions(-)