Git Hooks (and How They Work)

Whenever you initialize a git repository with git init a .git/hooks directory is created. Git comes with a few helpful examples loaded in this directory. These example scripts will run if you want to use them, but in most cases they simply provide a helpful template for how you can configure your own scripts.

Before configuring your hooks, you should know the difference between exit codes 0 and non-zero. Exit codes can be used in scripts to indicate a stopping point or signal to halt execution. An exit code of 0 (zero) means that everything ran successfully, while a non-zero can indicate a problem or introduce alternate logic.

As you’re reading about and configuring your own git hooks, bear in mind that “non-zero status” simply means that an alternate path will be taken to disrupt the event that triggered the hook.

Local hooks, also known as “client-side” hooks, run on your local repository. This means you can customize these local scripts for your environment without affecting any other contributors out in the web.

Most common, you will see a “pre-commit” hook utilized on the local repository. This script will run before you are even prompted to provide a commit message. The pre-commit hook, ideal for testing, allows you to run scripts on your current commit, possibly saving you from committing errors to the repository.

Once you have initialized a git repository locally, you can take a look at your hook samples by opening the hooks directory.

From the repository working directory, type:

cd .git/hooks

Or, if you prefer to use the file manager in your operating system, make sure that the “hidden files” are visible, then open the .git directory. You will see the hooks directory sitting right there waiting for you.

Notice that all the scripts listed here end with a .sample extension. In order to make these scripts executable you must remove this sample extension and leave the hook as is.

On the command line, you can use the mv command to rename these files. For example, using the pre-commit.sample file:

mv pre-commit.sample pre-commit

Now if you try to run a commit, you will receive a code review. Maybe your code will not trigger any warnings, but if so you can start to see how powerful these hooks can be.

Remote hooks, also known as “server-side” hooks (because they happen on a remote server), can be used to trigger actions at—of course—the server side of your Git project. Most Git projects have a remote repository on a server. This is how various users from different locations can contribute to the same project.

Since these hooks are triggered at the remote location, they will affect all users (if there are other users besides yourself). So it is best to make sure that these scripts are secure and will not tamper with anyone else’s workflow.

A great way to use the server-side hooks is to trigger actions around a git push. For example, you can write a script that places your entire commit tree in a zipped archive with the version number appended to the file. You could use a “post-receive” hook to trigger a git checkout, in effect publishing the files to a different location on the server.

You may also be interested in some follow-up reading:

• Complete git hook documentation
• Learn git in 7 minutes