Depending on your exact version of Git, you may find some hooks in your repository at the time it’s created. Hooks are copied automatically from your Git template directory when you create a new repository. On Debian and Ubuntu, for example, the hooks are copied from /usr/share/git-core/templates/hooks. Most Git versions include some example hooks that you can use, and these are preinstalled for you in the templates directory.

Here’s what you need to know about the example hooks:

Originally, each example hook was simply copied into the .git/hooks/ directory from the template directory with its execute permission removed. You could then enable the hook by setting its execute bit.

That worked fine on systems like Unix and Linux, but didn’t work well on Windows. In Windows, file permissions work differently and, unfortunately, files are executable by default. This meant the example hooks were executable by default, causing great confusion among new Git users because all the hooks ran when none should have.

Because of this problem with Windows, newer versions of Git suffix each hook file name with .sample so it won’t run even if it’s executable. To enable the example hooks, you’ll have to rename the appropriate scripts yourself.

If you aren’t interested in the example hooks, it is perfectly safe to remove them from your repository: rm .git/hooks/*. You can always get them back by copying them from their home in the templates directory.

To explore how a hook works, let’s create a new repository and install a simple hook. First, we create the repository and populate it with a few files:

    $ mkdir hooktest

    $ cd hooktest

    $ git init
    Initialized empty Git repository in .git/

    $ touch a b c

    $ git add a b c

    $ git commit -m 'added a, b, and c'
    Created initial commit 97e9cf8: added a, b, and c
     0 files changed, 0 insertions(+), 0 deletions(-)
     create mode 100644 a
     create mode 100644 b
     create mode 100644 c

Next, let’s create a pre-commit hook to prevent checking in changes that contain the word “broken.” Using your favorite text editor, put the following in a file called .git/hooks/pre-commit:

    #!/bin/bash
    echo "Hello, I'm a pre-commit script!" >&2
    if git diff --cached | grep '^+' | grep -q 'broken'; then
            echo "ERROR: Can't commit the word 'broken'" >&2
            exit 1  # reject
    fi
    exit 0  # accept

The script generates a list of all differences about to be checked in, extracts the lines to be added (that is, those lines that begin with a + character), and scans those lines for the word “broken.”

There are many ways to test for the word “broken,” but most of the obvious ones result in subtle problems. I’m not talking about how to “test for the word ‘broken’” but rather about how to find the text to be scanned for the word “broken.”

For example, you might have tried the test:

    if git ls-files | xargs grep -q 'broken'; then

or, in other words, search for the word “broken,” in all files in the repository. But this approach has two problems. If someone else had already committed a file containing the word “broken,” then this script would prevent all future commits (until you fix it), even if those commits are totally unrelated. Moreover, the Unix grep command has no way of knowing which files will actually be committed; if you add “broken” to file b, make an unrelated change to a, and then run git commit a, there’s nothing wrong with your commit because you’re not trying to commit b. However, a script with this test would reject it anyway.

Now that you’ve created the pre-commit hook, make sure it’s executable:

    $ chmod a+x .git/hooks/pre-commit

And now you can test that it works as expected:

    $ echo "perfectly fine" >a

    $ echo "broken" >b

    # Try to commit all files, even a 'broken' one.
    $ git commit -m "test commit -a" -a
    Hello, I'm a pre-commit script!
    ERROR: Can't commit the word 'broken'

    # Selectively committing un-broken files works.
    $ git commit -m "test only file a" a
    Hello, I'm a pre-commit script!
    Created commit 4542056: test
    1 files changed, 1 insertions(+), 0 deletions(-)

    # And committing 'broken' files won't work.
    $ git commit -m "test only file b" b
    Hello, I'm a pre-commit script!
    ERROR: Can't commit the word 'broken'

Observe that even when a commit works, the pre-commit script still emits “Hello.” This would be annoying in a real script, so you should use such messages only while debugging the script. Notice also that, when the commit is rejected, git commit doesn’t print an error message; the only message is the one produced by the script. To avoid confusing the user, be careful always to print an error message from a “pre” script if it’s going to return a nonzero (“reject”) exit code.

Given those basics, let’s talk about the different hooks you can create.

When you run git commit, Git executes a process like that shown in Figure 15-1.

Figure 15-1. Commit hook processing

Each hook has its own purpose as follows:

When you run git am, Git executes a process like that shown in Figure 15-2.

Figure 15-2. Patch hook processing

When you run git push, the receiving end of Git executes a process like the one shown in Figure 15-3.

Figure 15-3. Receive hook processing

As you can see in the diagram, the very first step of git push is to transfer all the missing objects (blobs, trees, and commits) from your local repository to the remote one. There is no need for a hook during this process because all Git objects are identified by their unique SHA1 hash; your hook cannot modify an object because it would change the hash. Furthermore, there’s no reason to reject an object, because git gc cleans up anyway if the object turns out to be unneeded.

Instead of manipulating the objects themselves, push-related hooks are called when it’s time to update the refs (branches and tags).

Finally, there are a few miscellaneous hooks, and by the time you read this there may be even more. (Again, you can find the list of available hooks quickly with the command git help hooks.)