[PATCH] githooks.txt: Clarify documentation on reference-transaction hook

From: Patrick Steinhardt <ps@pks.im>
Date: Feb 25, 2021, 05:50 UTC
Message-ID: <c30d41de55b8991a09e1d550e853f582b5394dee.1614232040.git.ps@pks.im>

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

I've been postponing doing this simple doc update for far too long, but here it finally is. It simply clarifies its current workings and limitations without changing anything. This is not supposed to be a "We don't want it to ever cover symrefs", but rather to avoid confusion.

Patrick

 Documentation/githooks.txt | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index 1f3b57d04d..b01de04702 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -473,7 +473,8 @@ reference-transaction
 
 This hook is invoked by any Git command that performs reference
 updates. It executes whenever a reference transaction is prepared,
-committed or aborted and may thus get called multiple times.
+committed or aborted and may thus get called multiple times. The hook
+does not cover symbolic references.
 
 The hook takes exactly one argument, which is the current state the
 given reference transaction is in:
@@ -492,6 +493,13 @@ receives on standard input a line of the format:
 
   <old-value> SP <new-value> SP <ref-name> LF
 
+where `<old-value>` is the old object name passed into the reference
+transaction, `<new-value>` is the new object name to be stored in the
+ref and `<ref-name>` is the full name of the ref. When force updating
+the reference regardless of its current value or when the reference is
+to be created anew, `<old-value>` is 40 `0`. To distinguish these cases,
+you can inspect the current value of `<ref-name>` via `git rev-parse`.
+
 The exit status of the hook is ignored for any state except for the
 "prepared" state. In the "prepared" state, a non-zero exit status will
 cause the transaction to be aborted. The hook will not be called with

-- 
2.30.1