diff options
Diffstat (limited to 'Documentation/githooks.txt')
| -rw-r--r-- | Documentation/githooks.txt | 303 |
1 files changed, 303 insertions, 0 deletions
diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt new file mode 100644 index 0000000000..4f06ae0ed4 --- /dev/null +++ b/Documentation/githooks.txt @@ -0,0 +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` 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: + + <old-value> SP <new-value> SP <ref-name> LF + +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, `<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. + +[[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 +<<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. + +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 +<<pre-receive,'pre-receive'>> +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 <<post-update,'post-update'>> 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 +<<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 +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[1] suite |