Re: [PATCH v2 2/2] githooks.txt: Clarify documentation on reference-transaction hook
From: Junio C Hamano <hidden>
Date: 2021-03-01 16:58:57
Patrick Steinhardt [off-list ref] writes:
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.
Sounds good (especially "that may change in the future" part is a nice touch). Thanks.
quoted hunk
Signed-off-by: Patrick Steinhardt <redacted> --- Documentation/githooks.txt | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-)diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 4dad80052e..b51959ff94 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 (but that may change in the future). The hook takes exactly one argument, which is the current state the given reference transaction is in:@@ -492,6 +493,14 @@ 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 the all-zeroes object name. 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