summaryrefslogtreecommitdiff
path: root/Documentation/hooks.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/hooks.txt')
-rw-r--r--Documentation/hooks.txt159
1 files changed, 159 insertions, 0 deletions
diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt
new file mode 100644
index 0000000..b083290
--- /dev/null
+++ b/Documentation/hooks.txt
@@ -0,0 +1,159 @@
+Hooks used by git
+=================
+
+Hooks are little scripts you can place in `$GIT_DIR/hooks`
+directory to trigger action at certain points. When
+`git-init` is run, a handful example hooks are copied in the
+`hooks` directory of the new repository, but by default they are
+all disabled. To enable a hook, make it executable with `chmod +x`.
+
+This document describes the currently defined hooks.
+
+applypatch-msg
+--------------
+
+This hook is invoked by `git-applypatch` script, which is
+typically invoked by `git-applymbox`. It takes a single
+parameter, the name of the file that holds the proposed commit
+log message. Exiting with non-zero status causes
+`git-applypatch` to abort before applying the patch.
+
+The hook is allowed to edit the message file in place, and can
+be used to normalize the message into some project standard
+format (if the project has one). It can also be used to refuse
+the commit after inspecting the message file.
+
+The default 'applypatch-msg' hook, when enabled, runs the
+'commit-msg' hook, if the latter is enabled.
+
+pre-applypatch
+--------------
+
+This hook is invoked by `git-applypatch` script, which is
+typically invoked by `git-applymbox`. It takes no parameter,
+and is invoked after the patch is applied, but before a commit
+is made. Exiting with non-zero status causes the working tree
+after application of the patch not committed.
+
+It can be used to inspect the current working tree and refuse to
+make a commit if it does not pass certain test.
+
+The default 'pre-applypatch' hook, when enabled, runs the
+'pre-commit' hook, if the latter is enabled.
+
+post-applypatch
+---------------
+
+This hook is invoked by `git-applypatch` script, which is
+typically invoked by `git-applymbox`. It takes no parameter,
+and is invoked after the patch is applied and a commit is made.
+
+This hook is meant primarily for notification, and cannot affect
+the outcome of `git-applypatch`.
+
+pre-commit
+----------
+
+This hook is invoked by `git-commit`, and can be bypassed
+with `\--no-verify` option. It takes no parameter, and is
+invoked before obtaining the proposed commit log message and
+making a commit. Exiting with non-zero status from this script
+causes the `git-commit` to abort.
+
+The default 'pre-commit' hook, when enabled, catches introduction
+of lines with trailing whitespaces and aborts the commit when
+such a line is found.
+
+commit-msg
+----------
+
+This hook is invoked by `git-commit`, and can be bypassed
+with `\--no-verify` option. It takes a single parameter, the
+name of the file that holds the proposed commit log message.
+Exiting with non-zero status causes the `git-commit` to
+abort.
+
+The hook is allowed to edit the message file in place, and can
+be used to normalize the message into some project standard
+format (if the project has one). It can also be used to refuse
+the commit after inspecting the message file.
+
+The default 'commit-msg' hook, when enabled, detects duplicate
+"Signed-off-by" lines, and aborts the commit if one is found.
+
+post-commit
+-----------
+
+This hook is invoked by `git-commit`. It takes no
+parameter, and is invoked after a commit is made.
+
+This hook is meant primarily for notification, and cannot affect
+the outcome of `git-commit`.
+
+update
+------
+
+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 updating the ref on the remote repository, the update hook
+is invoked. Its exit status determines the success or failure of
+the ref update.
+
+The hook executes once for each ref to be updated, and takes
+three parameters:
+
+ - the name of the ref being updated,
+ - the old object name stored in the ref,
+ - and the new objectname to be stored in the ref.
+
+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.
+
+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
+descendant of the commit object named by the old object name.
+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.
+
+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.
+
+The default 'update' hook, when enabled, demonstrates how to
+send out a notification e-mail.
+
+post-update
+-----------
+
+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.
+
+It takes a variable number of parameters, each of which is the
+name of ref that was actually updated.
+
+This hook is meant primarily for notification, and cannot affect
+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.
+
+When enabled, the default 'post-update' hook runs
+`git-update-server-info` to keep the information used by dumb
+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`.