From: Junio C Hamano Date: Wed, 14 May 2008 20:34:23 +0000 (-0700) Subject: Merge branch 'cc/hooks-doc' X-Git-Tag: v1.5.6-rc0~59 X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=29182f7da4b31b11f82281a9a03edd082975dceb;p=git.git Merge branch 'cc/hooks-doc' * cc/hooks-doc: Documentation: rename "hooks.txt" to "githooks.txt" and make it a man page --- 29182f7da4b31b11f82281a9a03edd082975dceb diff --cc Documentation/githooks.txt index 000000000,67c0809f7..53747febd mode 000000,100644..100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@@ -1,0 -1,302 +1,303 @@@ + githooks(5) + =========== + + NAME + ---- + githooks - Hooks used by git + + SYNOPSIS + -------- + $GIT_DIR/hooks/* + + + DESCRIPTION + ----------- + + 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-am` script. It takes a single + parameter, the name of the file that holds the proposed commit + log message. Exiting with non-zero status causes + `git-am` 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-am`. It takes no parameter, and is + invoked after the patch is applied, but before a commit is made. + + If it exits with non-zero status, then the working tree will not be + committed after applying the patch. + + 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-am`. 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-am`. + + 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. + + All the `git-commit` hooks are invoked with the environment + variable `GIT_EDITOR=:` if the command will not bring up an editor + to modify the commit message. + + prepare-commit-msg + ------------------ + + This hook is invoked by `git-commit` right after preparing the + default log message, and before the editor is started. + + It takes one to three parameters. The first is the name of the file + that the commit log message. The second is the source of the commit + message, and can be: `message` (if a `\-m` or `\-F` option was + given); `template` (if a `\-t` option was given or the + configuration option `commit.template` is set); `merge` (if the + commit is a merge or a `.git/MERGE_MSG` file exists); `squash` + (if a `.git/SQUASH_MSG` file exists); or `commit`, followed by + a commit SHA1 (if a `\-c`, `\-C` or `\--amend` option was given). + + If the exit status is non-zero, `git-commit` will abort. + + The purpose of the hook is to edit the message file in place, and + it is not suppressed by the `\--no-verify` option. A non-zero exit + means a failure of the hook and aborts the commit. It should not + be used as replacement for pre-commit hook. + + The sample `prepare-commit-msg` hook that comes with git comments + out the `Conflicts:` part of a merge's commit message. + + 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`. + + post-checkout + ----------- + + This hook is invoked when a `git-checkout` is run after having updated the + worktree. The hook is given three parameters: the ref of the previous HEAD, + the ref of the new HEAD (which may or may not have changed), and a flag + indicating whether the checkout was a branch checkout (changing branches, + flag=1) or a file checkout (retrieving a file from the index, flag=0). + This hook cannot affect the outcome of `git-checkout`. + + This hook can be used to perform repository validity checks, auto-display + differences from the previous HEAD if different, or set working dir metadata + properties. + + post-merge + ----------- + + This hook is invoked by `git-merge`, which happens when a `git pull` + is done on a local repository. The hook takes a single parameter, a status + flag specifying whether or not the merge being done was a squash merge. -This hook cannot affect the outcome of `git-merge`. ++This hook cannot affect the outcome of `git-merge` and is not executed, ++if the merge failed due to conflicts. + + This hook can be used in conjunction with a corresponding pre-commit hook to + save and restore any form of metadata associated with the working tree + (eg: permissions/ownership, ACLS, etc). See contrib/hooks/setgitperms.perl + for an example of how to do this. + + [[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: + + SP SP LF + + where `` is the old object name stored in the ref, + `` is the new object name to be stored in the ref and + `` is the full name of the ref. + When creating a new ref, `` 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 <> 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. + + [[update]] + 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 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 + 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. The + <> 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. + + 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 gets the same information as the + <> + hook does on its standard input. + + This hook does not affect the outcome of `git-receive-pack`, as it + is called after the real work is done. + + This supersedes the <> hook in that it gets + 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 'post-receive' hook is empty, but there is + a sample script `post-receive-email` provided in the `contrib/hooks` + directory in git distribution, which implements sending commit + emails. + + [[post-update]] + 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. The + <> 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 + 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. + + 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. + + pre-auto-gc + ----------- + + This hook is invoked by `git-gc --auto`. It takes no parameter, and + exiting with non-zero status from this script causes the `git-gc --auto` + to abort. + + GIT + --- + Part of the linkgit:git[7] suite