githooks.txt: clarify documentation on reference-transaction hook
The reference-transaction hook doesn't clearly document its scope and what values it receives as input. Document it to make it less surprising and clearly delimit its (current) scope. Signed-off-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Patrick Steinhardt committed
Mar 1, 2021 at 10:43 UTC
23c781f1731bb77c16fb9c9a37e9d88f707af9bd
1 file changed
+10
-1
Documentation/githooks.txt
+10
-1
@@ -473,7 +473,8 @@ reference-transaction
473
474
This hook is invoked by any Git command that performs reference
475
updates. It executes whenever a reference transaction is prepared,
476
-committed or aborted and may thus get called multiple times.
476
+committed or aborted and may thus get called multiple times. The hook
477
+does not cover symbolic references (but that may change in the future).
478
479
The hook takes exactly one argument, which is the current state the
480
given reference transaction is in:
@@ -492,6 +493,14 @@ receives on standard input a line of the format:
493
494
<old-value> SP <new-value> SP <ref-name> LF
495
496
+where `<old-value>` is the old object name passed into the reference
497
+transaction, `<new-value>` is the new object name to be stored in the
498
+ref and `<ref-name>` is the full name of the ref. When force updating
499
+the reference regardless of its current value or when the reference is
500
+to be created anew, `<old-value>` is the all-zeroes object name. To
501
+distinguish these cases, you can inspect the current value of
502
+`<ref-name>` via `git rev-parse`.
503
+
504
The exit status of the hook is ignored for any state except for the
505
"prepared" state. In the "prepared" state, a non-zero exit status will
506
cause the transaction to be aborted. The hook will not be called with