aboutsummaryrefslogtreecommitdiff
path: root/README
blob: b5211bafd36d598ca8124fb26358d14263f3820d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
git-hooks - A tool to manage project, user, and global Git hooks for multiple git repositories.

git-hooks lets hooks be installed inside git repositories, users home directory, and globally.  When a hook is called by git, git-hooks will check each of these locations for the hooks to run.

************************************
Install

Add git-hooks to your PATH environment variable so 'git hooks' can be run.

Run 'git hooks --install' Inside a git project to change that projects git hooks to use git-hooks hooks.  'git hooks --uninstall' can be run at any time to go back to the old hooks that were installed before (typically the default which does nothing).

************************************
Overview

Hooks can be very powerful and useful.  Some common hooks include:

- Spell check the commit message.
- Check that the code builds.
- Verify that any new files contain a copyright with the current year in it.

Hooks can be very project specific such as:

- Verify that the project still builds
- Verify that autotests matching the modified files still pass with no errors.
- Pre-populate the commit message with the 'standard' format.
- Verify that any new code follows the 'standard' coding style.

or very specific to one person such as:

- Don't allow a push to a remote repository after 1am in case I break something and will be asleep.
- Don't let me commit between 9-5 for projects in ~/personal/ as I shouldn't be working on them during work hours.

For more details on the different Git hooks that can be installed checkout the online documentation at http://www.kernel.org/pub/software/scm/git/docs/githooks.html

************************************
Locations

git-hooks provide a way to manage and share your hooks by allowing for the installation of hooks in three locations:
 - User hooks that are installed in ~/.git_hooks/
 - Project hooks that are installed in the git_hooks directory inside of each project.
 - Global hooks that are specified with the hooks.global configuration option.
     The contrib directory includes a number of useful hooks and can be set by doing the following:
     git config --global hooks.global $PWD/contrib/

Multiple global hooks directories can be specified by using a space between each path.

************************************
Creating hooks

To keep things organized git-hooks looks for scripts in sub directories named after the git hook name.  For example this project has the following pre-commit script in the following location:

git_hooks/pre-commit/bsd

When you run 'git hooks' with no arguments it will list all of the hooks installed on the system.  It will run the hooks with the --about argument to generate the description that is shown.  Checkout the hooks in contrib for some examples.

************************************
Debugging

When GIT_HOOKS_VERBOSE is set git-hooks will output each hook as it is run so you can trouble shoot hooks that don't report errors, but exit with non-zero.

GIT_HOOKS_VERBOSE=1 git commit