{"thread":{"id":"3713","subject":"[PATCH] Clarify and expand some hook documentation.","startedAt":"2006-03-25T03:21:07Z","lastAt":"2006-03-25T03:21:07Z","messageCount":1,"participants":["Jon Loeliger"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"17900","messageId":"E1FMzKt-0006ur-Gj@jdl.com","threadId":"3713","inReplyTo":null,"subject":"[PATCH] Clarify and expand some hook documentation.","fromName":"Jon Loeliger","fromEmail":"jdl@jdl.com","sentAt":"2006-03-25T03:21:07Z","receivedAt":"2006-03-25T03:21:07Z","isPatch":true,"sender":{"key":"jdl@jdl.com","avatar":"https://gravatar.com/avatar/75ce9a10b151acd2c28ec4ab2136dba7b2ff1634530bd04b155981a749d08a64?d=mp&s=160"},"body":"\nClarify update and post-update hooks.\nMade a few references to the hooks documentation.\n\nSigned-off-by: Jon Loeliger <jdl@jdl.com>\n\n---\n\n Documentation/git.txt               |    2 +\n Documentation/hooks.txt             |   49 ++++++++++++++++++++++++++---------\n Documentation/repository-layout.txt |    2 +\n 3 files changed, 41 insertions(+), 12 deletions(-)\n\n83472863b77cde6209ce01211500e2bd9b81ecc7\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex de3934d..0c424ff 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -531,6 +531,8 @@ File/Directory Structure\n \n Please see link:repository-layout.html[repository layout] document.\n \n+Read link:hooks.html[hooks] for more details about each hook.\n+\n Higher level SCMs may provide and manage additional information in the\n `$GIT_DIR`.\n \ndiff --git a/Documentation/hooks.txt b/Documentation/hooks.txt\nindex 4ad1920..3824a95 100644\n--- a/Documentation/hooks.txt\n+++ b/Documentation/hooks.txt\n@@ -97,16 +97,31 @@ send out a commit notification e-mail.\n update\n ------\n \n-This hook is invoked by `git-receive-pack`, which is invoked\n-when a `git push` is done against the repository.  It takes\n-three parameters, name of the ref being updated, old object name\n-stored in the ref, and the new objectname to be stored in the\n-ref.  Exiting with non-zero status from this hook prevents\n-`git-receive-pack` from updating the ref.\n+This hook is invoked by `git-receive-pack` on the remote repository,\n+which is happens when a `git push` is done on a local repository.\n+Just before updating the ref on the remote repository, the update hook\n+is invoked.  It's exit status determins the success or failure of\n+the ref update.\n+\n+The hook executes once for each ref to be updated, and takes\n+three parameters:\n+    - the name of the ref being updated,\n+    - the old object name stored in the ref,\n+    - and the new objectname to be stored in the ref.\n+\n+A zero exit from the update hook allows the ref to be updated.\n+Exiting with a non-zero status prevents `git-receive-pack`\n+from updating the ref.\n \n-This can be used to prevent 'forced' update on certain refs by\n+This hook can be used to prevent 'forced' update on certain refs by\n making sure that the object name is a commit object that is a\n descendant of the commit object named by the old object name.\n+That is, to enforce a \"fast forward only\" policy.\n+\n+It could also be used to log the old..new status.  However, it\n+does not know the entire set of branches, so it would end up\n+firing one e-mail per ref when used naively, though.\n+\n Another use suggested on the mailing list is to use this hook to\n implement access control which is finer grained than the one\n based on filesystem group.\n@@ -115,20 +130,30 @@ The standard output of this hook is sent\n want to report something to the git-send-pack on the other end,\n you can redirect your output to your stderr.\n \n+\n post-update\n -----------\n \n-This hook is invoked by `git-receive-pack`, which is invoked\n-when a `git push` is done against the repository.  It takes\n-variable number of parameters; each of which is the name of ref\n-that was actually updated.\n+This hook is invoked by `git-receive-pack` on the remote repository,\n+which is happens when a `git push` is done on a local repository.\n+It executes on the remote repository once after all the refs have\n+been updated.\n+\n+It takes a variable number of parameters, each of which is the\n+name of ref that was actually updated.\n \n This hook is meant primarily for notification, and cannot affect\n the outcome of `git-receive-pack`.\n \n+The post-update hook can tell what are the heads that were pushed,\n+but it does not know what their original and updated values are,\n+so it is a poor place to do log old..new.\n+\n The default post-update hook, when enabled, runs\n `git-update-server-info` to keep the information used by dumb\n-transport up-to-date.\n+transports (eg, http) up-to-date.  If you are publishing\n+a git repository that is accessible via http, you should\n+probably enable this hook.\n \n The standard output of this hook is sent to /dev/null; if you\n want to report something to the git-send-pack on the other end,\ndiff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt\nindex 1f19bf8..98fbe7d 100644\n--- a/Documentation/repository-layout.txt\n+++ b/Documentation/repository-layout.txt\n@@ -89,6 +89,8 @@ hooks::\n \tcommands.  A handful of sample hooks are installed when\n \t`git init-db` is run, but all of them are disabled by\n \tdefault.  To enable, they need to be made executable.\n+\tRead link:hooks.html[hooks] for more details about\n+\teach hook.\n \n index::\n \tThe current index file for the repository.  It is\n-- \n1.2.4.gdd7be\n"}]}