Updated documentation of hooks in git-receive-pack.
PATCH 1/1 Updated documentation of hooks in git-receive-pack.
Added documentation of pre-receive and post-receive hooks and updated documentation of update and post-update hooks.
---
Recent question on the mailing-list made me to look at the post-receive hook in the Documentation/hooks.txt, only to find it is not mentioned there at all.
I looked up all the hooks and how they are called in receive-pack.c and updated the documentation for them. Please review and apply.
Feel free to suggest syntactic or semantic fixes; I am not a native English speaker, so there may well be some.
Regards,
Jan
Documentation/hooks.txt | 84 ++++++++++++++++++++++++++++++++++++++++++---- 1 files changed, 76 insertions(+), 8 deletions(-)
Documentation/hooks.txt +76 -8
@@ -90,6 +90,37 @@ parameter, and is invoked after a commit is made. This hook is meant primarily for notification, and cannot affect the outcome of `git-commit`. +[[pre-receive]] +pre-receive +----------- + +This hook is invoked by `git-receive-pack` on the remote repository, +which happens when a `git push` is done on a local repository. +Just before starting to update refs on the remote repository, the +pre-receive hook is invoked. Its exit status determines the success +or failure of the update. + +This hook executes once for the receive operation. It takes no +arguments, but for each ref to be updated it receives on standard +input a line of the format: + + <old-value> SP <new-value> SP <ref-name> NL + +where `<old-value>` is the old object name stored in the ref, +`<new-value>` is the new object name to be stored in the ref and +`<ref-name>` is the full name of the ref. + +If the hook exits with non-zero status, none of the refs will be +updated. If the hook returs zero, updating of individual refs can +still be prevented by the <<update,'update'>> hook. + +The standard output of this hook is sent to `stderr`, so if you +want to report something to the `git-send-pack` on the other end, +you can simply `echo` your messages. + +There is no default 'pre-receive' hook. + +[[update]] update ------
@@ -108,7 +139,7 @@ three parameters: A zero exit from the update hook allows the ref to be updated. Exiting with a non-zero status prevents `git-receive-pack` -from updating the ref. +from updating that ref. This hook can be used to prevent 'forced' update on certain refs by making sure that the object name is a commit object that is a
@@ -117,7 +148,8 @@ That is, to enforce a "fast forward only" policy. It could also be used to log the old..new status. However, it does not know the entire set of branches, so it would end up -firing one e-mail per ref when used naively, though. +firing one e-mail per ref when used naively, though. The +<<post-receive,'post-receive'>> hook is more suited to that. Another use suggested on the mailing list is to use this hook to implement access control which is finer grained than the one
@@ -127,9 +159,45 @@ The standard output of this hook is sent to `stderr`, so if you want to report something to the `git-send-pack` on the other end, you can simply `echo` your messages. -The default 'update' hook, when enabled, demonstrates how to -send out a notification e-mail. +The default 'update' hook, when enabled--and with +`hooks.allowunannotated` config option turned on--prevents +unannotated tags to be pushed. +[[post-receive]] +post-receive +------------ + +This hook is invoked by `git-receive-pack` on the remote repository, +which happens when a `git push` is done on a local repository. +It executes on the remote repository once after all the refs have +been updated. + +This hook executes once for the receive operation. It takes no +arguments, but for each ref that was updated it receives on standard +input a line of the format: + + <old-value> SP <new-value> SP <ref-name> NL + +on stdin, where `<old-value>` is the old object name stored in the +ref, `<new-value>` is the new object name to be stored in the ref and +`<ref-name>` is the full name of the ref. + +This hook cannot affect the outcome of `git-receive-pack`, as it's +called after the real work is done. + +This superceedes the [[post-update]] hook in that it actually get's +both old and new values of all the refs. + +The standard output of this hook is sent to `stderr`, so if you +want to report something to the `git-send-pack` on the other end, +you can simply `echo` your messages. + +The default 'post-receive' hook is empty, but there is +a script `post-receive-email` provided in the `contrib/hooks` +directory in git distribution, which implements sending commit +emails. + +[[post-update]] post-update -----------
@@ -146,7 +214,8 @@ the outcome of `git-receive-pack`. The 'post-update' hook can tell what are the heads that were pushed, but it does not know what their original and updated values are, -so it is a poor place to do log old..new. +so it is a poor place to do log old..new. See +<<post-receive,'post-receive'>> hook above for a better one. When enabled, the default 'post-update' hook runs `git-update-server-info` to keep the information used by dumb
@@ -154,6 +223,5 @@ transports (e.g., HTTP) up-to-date. If you are publishing a git repository that is accessible via HTTP, you should probably enable this hook. -The standard output of this hook is sent to `/dev/null`; if you -want to report something to the `git-send-pack` on the other end, -you can redirect your output to your `stderr`. +Both standard output and standard error output are forwarded to +`git-send-pack` on the other end.
Signature · 1 line
1.5.1.4
Quoted 4 lines · Jan Hudec
Added documentation of pre-receive and post-receive hooks and updated documentation of update and post-update hooks.
Signed-off-by Jan Hudec <[email protected]>
Thanks, much appreciated. Domain ucw.cz sounds familiar; are you close by to Pasky?
Documentation/hooks.txt parameter, and is invoked after a commit is made. · line 111
Quoted 12 lines
+[[pre-receive]]
Documentation/hooks.txt +10
-0+pre-receive +This hook executes once for the receive operation. It takes no +arguments, but for each ref to be updated it receives on standard +input a line of the format: + + <old-value> SP <new-value> SP <ref-name> NL + +where `<old-value>` is the old object name stored in the ref, +`<new-value>` is the new object name to be stored in the ref and +`<ref-name>` is the full name of the ref.
s/NL/LF/
When creating a new ref, <old-value> is 40 0.
Documentation/hooks.txt parameter, and is invoked after a commit is made. · line 115
Quoted 3 lines
Documentation/hooks.txt +3
-0+If the hook exits with non-zero status, none of the refs will be +updated. If the hook returs zero, updating of individual refs can +still be prevented by the <<update,'update'>> hook.
s/returs/exits with/
Documentation/hooks.txt parameter, and is invoked after a commit is made. · line 119
Quoted 3 lines
Documentation/hooks.txt +3
-0+The standard output of this hook is sent to `stderr`, so if you +want to report something to the `git-send-pack` on the other end, +you can simply `echo` your messages.
I think "sent to stderr" is a implementation detail between receive-pack and hook scripts. I would just keep the "if you want to..." part.
Quoted 8 lines
+[[post-receive]]
Documentation/hooks.txt +7
-0+post-receive +------------ + +This hook is invoked by `git-receive-pack` on the remote repository, +which happens when a `git push` is done on a local repository. +It executes on the remote repository once after all the refs have +been updated.
Documentation/hooks.txt The standard output of this hook is sent to `stderr`, so if you · line 183
Quoted 10 lines
Documentation/hooks.txt +10
-0+ +This hook executes once for the receive operation. It takes no +arguments, but for each ref that was updated it receives on standard +input a line of the format: + + <old-value> SP <new-value> SP <ref-name> NL + +on stdin, where `<old-value>` is the old object name stored in the +ref, `<new-value>` is the new object name to be stored in the ref and +`<ref-name>` is the full name of the ref.
Maybe
It takes no arguments, but gets the same information as the pre-receive hook does on its standard input.
to avoid the duplicated description.
Documentation/hooks.txt The standard output of this hook is sent to `stderr`, so if you · line 189
Quoted 5 lines
Documentation/hooks.txt +5
-0+This hook cannot affect the outcome of `git-receive-pack`, as it's +called after the real work is done. + +This superceedes the [[post-update]] hook in that it actually get's +both old and new values of all the refs.
s/superceedes/supersedes/
Documentation/hooks.txt parameter, and is invoked after a commit is made. · line 119
Quoted 3 lines
Documentation/hooks.txt +3
-0+The standard output of this hook is sent to `stderr`, so if you +want to report something to the `git-send-pack` on the other end, +you can simply `echo` your messages.
Ditto.
Documentation/hooks.txt the outcome of `git-receive-pack`. · line 218
Quoted 11 lines
+[[post-update]]
post-update
-----------Documentation/hooks.txt +2
-1@@ -146,7 +214,8 @@ the outcome of `git-receive-pack`. The 'post-update' hook can tell what are the heads that were pushed, but it does not know what their original and updated values are, -so it is a poor place to do log old..new. +so it is a poor place to do log old..new. See +<<post-receive,'post-receive'>> hook above for a better one.
Instead of just passing 'a better one' judgement without rationale, it is more helpful to explain why the newer ones are recommended, so that the reader can agree to it.
In general, post-receive hook is preferred when the hook needs to decide its acion on the status of the entire set of refs being updated, as this hook is called once per ref, with information only on a single ref at a time.
Quoted 9 lines · Junio C Hamano
Quoted 4 lines · Jan Hudec
Added documentation of pre-receive and post-receive hooks and updated documentation of update and post-update hooks.
Signed-off-by Jan Hudec <[email protected]>Thanks, much appreciated. Domain ucw.cz sounds familiar; are you close by to Pasky?
Studied the same faculty.
Quoted 8 lines
[...]
Documentation/hooks.txt parameter, and is invoked after a commit is made. · line 119
Quoted 3 lines
Documentation/hooks.txt +3
-0+The standard output of this hook is sent to `stderr`, so if you +want to report something to the `git-send-pack` on the other end, +you can simply `echo` your messages.I think "sent to stderr" is a implementation detail between receive-pack and hook scripts. I would just keep the "if you want to..." part.
It's actually original wording from description of 'update'. I think just leaving out the stderr thing is not right, because it's important that both stdout and stderr go to the same place. I'll change it to:
Both standard output and error output are forwarded to git-send-pack on the other end, so you can simply echo messages for the user.
Quoted 21 lines
Quoted 8 lines
+[[post-receive]]
Documentation/hooks.txt +7
-0+post-receive +------------ + +This hook is invoked by `git-receive-pack` on the remote repository, +which happens when a `git push` is done on a local repository. +It executes on the remote repository once after all the refs have +been updated.Documentation/hooks.txt The standard output of this hook is sent to `stderr`, so if you · line 183
Quoted 10 lines
Documentation/hooks.txt +10
-0+ +This hook executes once for the receive operation. It takes no +arguments, but for each ref that was updated it receives on standard +input a line of the format: + + <old-value> SP <new-value> SP <ref-name> NL + +on stdin, where `<old-value>` is the old object name stored in the +ref, `<new-value>` is the new object name to be stored in the ref and +`<ref-name>` is the full name of the ref.Maybe
Quoted 4 lines
It takes no arguments, but gets the same information as the
pre-receivehook does on its standard input.to avoid the duplicated description.
Makes sense.
Quoted 16 lines
Documentation/hooks.txt the outcome of `git-receive-pack`. · line 218
Quoted 11 lines
+[[post-update]]
post-update
-----------Documentation/hooks.txt +2
-1@@ -146,7 +214,8 @@ the outcome of `git-receive-pack`. The 'post-update' hook can tell what are the heads that were pushed, but it does not know what their original and updated values are, -so it is a poor place to do log old..new. +so it is a poor place to do log old..new. See +<<post-receive,'post-receive'>> hook above for a better one.Instead of just passing 'a better one' judgement without rationale, it is more helpful to explain why the newer ones are recommended, so that the reader can agree to it.
Quoted 4 lines
In general,
post-receivehook is preferred when the hook needs to decide its acion on the status of the entire set of refs being updated, as this hook is called once per ref, with information only on a single ref at a time.
Yes, it's probably better. Though in this case the post-update hook should be really obsoleted. It takes names of all updated refs on command-line, which is unlikely to fail on linux, but might fail on Windows where the command-line lenght is much more limited. But for now I'll just mention that the other hook does have the information this one does not.
Signature · 1 line
Jan 'Bulb' Hudec <[email protected]>
PATCH 1/1 Updated documentation of hooks in git-receive-pack.
Added documentation of pre-receive and post-receive hooks and updated documentation of update and post-update hooks.
---
Resubmitting the patch including the changes based on review.
Documentation/hooks.txt | 90 +++++++++++++++++++++++++++++++++++++++++------ 1 files changed, 79 insertions(+), 11 deletions(-)
Documentation/hooks.txt +79 -11
@@ -90,6 +90,38 @@ parameter, and is invoked after a commit is made. This hook is meant primarily for notification, and cannot affect the outcome of `git-commit`. +[[pre-receive]] +pre-receive +----------- + +This hook is invoked by `git-receive-pack` on the remote repository, +which happens when a `git push` is done on a local repository. +Just before starting to update refs on the remote repository, the +pre-receive hook is invoked. Its exit status determines the success +or failure of the update. + +This hook executes once for the receive operation. It takes no +arguments, but for each ref to be updated it receives on standard +input a line of the format: + + <old-value> SP <new-value> SP <ref-name> NL + +where `<old-value>` is the old object name stored in the ref, +`<new-value>` is the new object name to be stored in the ref and +`<ref-name>` is the full name of the ref. When creating a new ref, +the `<old-value>` is 40 `0`. + +If the hook exits with non-zero status, none of the refs will be +updated. If the hook exits with zero, updating of individual refs can +still be prevented by the <<update,'update'>> hook. + +Both standard output and standard error output are forwarded to +`git-send-pack` on the other end, so you can simply `echo` messages +for the user. + +There is no default 'pre-receive' hook. + +[[update]] update ------
@@ -108,7 +140,8 @@ three parameters: A zero exit from the update hook allows the ref to be updated. Exiting with a non-zero status prevents `git-receive-pack` -from updating the ref. +from updating that ref. When creating a new ref, +<old-value> is 40 `0`. This hook can be used to prevent 'forced' update on certain refs by making sure that the object name is a commit object that is a
@@ -117,19 +150,51 @@ That is, to enforce a "fast forward only" policy. It could also be used to log the old..new status. However, it does not know the entire set of branches, so it would end up -firing one e-mail per ref when used naively, though. +firing one e-mail per ref when used naively, though. The +<<post-receive,'post-receive'>> hook is more suited to that. Another use suggested on the mailing list is to use this hook to implement access control which is finer grained than the one based on filesystem group. -The standard output of this hook is sent to `stderr`, so if you -want to report something to the `git-send-pack` on the other end, -you can simply `echo` your messages. +Both standard output and standard error output are forwarded to +`git-send-pack` on the other end, so you can simply `echo` messages +for the user. + +The default 'update' hook, when enabled--and with +`hooks.allowunannotated` config option turned on--prevents +unannotated tags to be pushed. + +[[post-receive]] +post-receive +------------ + +This hook is invoked by `git-receive-pack` on the remote repository, +which happens when a `git push` is done on a local repository. +It executes on the remote repository once after all the refs have +been updated. + +This hook executes once for the receive operation. It takes no +arguments, but receives the same input as the +<<pre-receive,'pre-receive'>> hook. + +This hook cannot affect the outcome of `git-receive-pack`, as it's +called after the real work is done. + +This supersedes the <<post-update,'post-update'>> hook in that it +get's both old and new values of all the refs in addition to their +names. + +Both standard output and standard error output are forwarded to +`git-send-pack` on the other end, so you can simply `echo` messages +for the user. -The default 'update' hook, when enabled, demonstrates how to -send out a notification e-mail. +The default 'post-receive' hook is empty, but there is +a script `post-receive-email` provided in the `contrib/hooks` +directory in git distribution, which implements sending commit +emails. +[[post-update]] post-update -----------
@@ -146,7 +211,10 @@ the outcome of `git-receive-pack`. The 'post-update' hook can tell what are the heads that were pushed, but it does not know what their original and updated values are, -so it is a poor place to do log old..new. +so it is a poor place to do log old..new. The +<<post-receive,'post-receive'>> hook does get both original and +updated values of the refs. You might consider it instead if you need +them. When enabled, the default 'post-update' hook runs `git-update-server-info` to keep the information used by dumb
@@ -154,6 +222,6 @@ transports (e.g., HTTP) up-to-date. If you are publishing a git repository that is accessible via HTTP, you should probably enable this hook. -The standard output of this hook is sent to `/dev/null`; if you -want to report something to the `git-send-pack` on the other end, -you can redirect your output to your `stderr`. +Both standard output and standard error output are forwarded to +`git-send-pack` on the other end, so you can simply `echo` messages +for the user.
Signature · 1 line
1.5.1.4