Using Git Hooks in Your Development Workflow

Introduction

Git, a version control system created by Linus Torvalds, author of the Linux kernel, has become one of the most popular version control systems used globally. Certainly, this is because of its distributed nature, high performance, and reliability.

In this tutorial, we’ll look at git hooks. These hooks are a feature of git which furthers its extensibility by allowing developers to create event-triggered scripts.

We’ll look through the different types of git hooks and implement a few to get you well on the way to customizing your own.

A git hook is a script that git executes before or after a relevant git event or action is triggered.

Throughout the developer version control workflow, git hooks enable you to customize git’s internal behavior when certain events are triggered.

They can be used to perform actions such as:

1. Push to staging or production without leaving git
2. No need to mess with SSH or FTP
3. Prevent commits through enforcing commit policy.
4. Prevent pushes or merges that don’t conform to certain standards or meet guideline expectations.
5. Facilitate continuous deployment.

This proves extremely helpful for developers as git gives them the flexibility to fine-tune their development environment and automate development.

Prerequisites

Before we get started, there are a few key programs we need to install.

1. git
2. Node.js
3. bash

Confirm that you’ve installed them correctly by running the following in your terminal:

git --version && node --version && bash --version

You should see similar results

git version 2.7.4 (Apple Git-66)
v6.2.2
GNU bash, version 3.2.57(1)-release (x86_64-apple-darwin15)
Copyright (C) 2007 Free Software Foundation, Inc.

We’ll be using the following directory structure, so go ahead and lay out your project like this.

+-- git-hooks
    +-- custom-hooks
    +-- src
    |   +-- index.js
    +-- test
    |   +-- test.js
    +-- .jscsrc

That’s all for now as far as prerequisites go, so let’s dive in.

Types of git hooks

git hooks can be categorized into two main types. These are:

1. Client-side hooks
2. Server-side hooks

In this tutorial, we’ll focus more on client-side hooks. However, we will briefly discuss server-side hooks.

Client-Side Hooks

These are hooks installed and maintained on the developer’s local repository and are executed when events on the local repository are triggered. Because they are maintained locally, they are also known as local hooks.

Since they are local, they cannot be used as a way to enforce universal commit policies on a remote repository as each developer can alter their hooks. However, they make it easier for developers to adhere to workflow guidelines like linting and commit message guides.

Installing local hooks

Initialize the project we just created as a git repository by running

git init

Next, let’s navigate to the .git/hooks directory in our project and expose the contents of the folder

cd ./.git/hooks && ls

We’ll notice a few files inside the hooks directory, namely

applypatch-msg.sample
commit-msg.sample
post-update.sample
pre-applypatch.sample
pre-commit.sample
pre-push.sample
pre-rebase.sample
prepare-commit-msg.sample
update.sample

These scripts are the default hooks that git has so helpfully gifted us with. Notice that their names make reference to git events like pushes, commits, and rebases.

Useful in their own right, they also serve as a guideline on how hooks for certain events can be triggered.

The .sample extension prevents them from being run, so to enable them, remove the .sample extension from the script name.

The hooks we’ll write here will be in bash though you can use Python or even Perl. Git hooks can be written in any language as long as the file is executable.

We make the hook executable by using the chmod utility.

chmod +x .git/hooks/<insert-hook-name-here>

Order of execution

Mimicking the developer workflow for the commit process, hooks are executed in the following hierarchy.

        <pre-commit>
             |
    <prepare-commit-msg>
             |
        <commit-msg>
             |
       <post-commit>

pre-commit

The pre-commit hook is executed before git asks the developer for a commit message or creates a commit package. This hook can be used to make sure certain checks pass before a commit can be considered worthy to be made to the remote. No arguments are passed to the pre-commit script and if the script exists with a non-zero value, the commit event will be aborted.

Before we get into anything heavy, let’s create a simple pre-commit hook to get us comfortable.

Create a pre-commit hook inside the .git/hooks directory like this.

touch pre-commit && vi pre-commit

Enter the following into the pre-commit hook file

#!/bin/bash

echo "Can you make a commit? Well, it depends."
exit 1

Save and exit the editor by running:

esc then :wq

Don’t forget to make the hook file executable by running:

chmod + x .git/hooks/pre-commit

Let’s write out some code to test our newly minted hook against. At the root of our project, create a file called hello-world.py:

touch hello-world.py

Inside the file, enter the following:

print ('Hello Hooks') # python v3
# print 'Hello Hooks' # python v2

Next, let’s add the file into our git staging environment and begin a commit.

git add . && git commit

Are you surprised that git doesn’t let us commit our work?

As an experiment, modify the last line in the pre-commit hook we created from exit 1 to exit 0 and trigger another commit.

Now that we understand that a hook is just an event-triggered script, let’s create something with more utility.

In our example below, we want to make sure that all the tests for our code pass and that we have no linting errors before we commit.

We’re using mocha as our javascript test framework and jscs as our linter.

Fill the following into the .git/hooks/pre-commit file

#!/bin/bash

# Exits with non zero status if tests fail or linting errors exist
num_of_failures=`mocha -R json | grep failures -m 1 | awk '{print $2}' | sed 's/[,]/''/'`

errors=`jscs -r inline ./test/test.js`
num_of_linting_errors=`jscs -r junit ./test/test.js | grep failures -m 1 | awk '{print $4}' | sed 's/failures=/''/' | sed s/">"/''/ | sed s/\"/''/ | sed s/\"/''/`

if [ $num_of_failures != '0' ]; then
  echo "$num_of_failures tests have failed. You cannot commit until all tests pass.
        Commit exiting with a non-zero status."
  exit 1
fi

if [ $num_of_linting_errors !=  '0' ]; then
  echo "Linting errors present. $errors"
  exit 1
fi

Save the document and exit the vi editor as usual by using,

esc then :wq

The first line of the script indicates that we want the script to be run as a bash script. If the script was a python one, we would instead use

#!/usr/bin/env python

Make the file executable as we mentioned before by running

chmod +x .git/hooks/pre-commit

To give our commit hook something to test against, we’ll be creating a method that returns true when an input string contains vowels and false otherwise.

Create and populate a package.json file at the root of our git-hooks folder by running

npm init --yes

Install the project dependencies like this:

npm install chai mocha jscs --save-dev

Let’s write a test for our prospective hasVowels method.

git-hooks/test/test.js

const expect = require('chai').expect;
require('../src/index');

describe('Test hasVowels', () => {
  it('should return false if the string has no vowels', () => {
    expect('N VWLS'.hasVowels()).to.equal(false);
  });
  it('should return true if the string has vowels', () => {
    expect('No vowels'.hasVowels()).to.equal(true)

    // Introduce failing test
    expect('Has vowels'.hasVowels()).to.equal(false);
  });
});

git-hooks/src/index.js

// Method returns true if a vowel exists in the input string. Returns false otherwise.
String.prototype.hasVowels = function hasVowels() {
  const vowels = new RegExp('[aeiou]', 'i');
  return vowels.test(this);
};

To configure the jscs linter, fill the following into the .jscsrc file we’d created in the beginning.

.jscsrc

{
    "preset": "airbnb",
    "disallowMultipleLineBreaks": null,
    "requireSemicolons": true
}

Now add all the created files into the staging environment and trigger a commit.

git add .  && git commit

What do you think will happen?

You’re right. Git prevents us from making a commit. Rightfully so, because our tests have failed. Worry not. Our pre-commit script has helpfully provided us with hints regarding what could be wrong.

This is what it tells us:

1 tests have failed. You cannot commit until all tests pass.
        Commit exiting with a non-zero status.

If you can’t take my word for it, the screenshot below serves as confirmation.

Let’s fix things. Edit line 13 in test/test.js to

expect('Has vowels'.hasVowels()).to.equal(true);

Next, add the files to your staging environment, git add . like we did before, and git commit

Git still prevents us from committing.

Linting errors present. ./test/test.js: line 10, col 49, requireSemicolons: Missing semicolon after statement

Edit line 10 in test/test.js to

expect('No vowels'.hasVowels()).to.equal(true);

Now, running git commit after git add . should provide no challenges because our tests and linting have both passed.

You can skip the pre-commit hook by running git commit --no-verify.

prepare-commit-msg

The prepare-commit-msg hook is executed after the pre-commit hook and its execution populates the vi editor commit message.

This hook takes one, two, or three arguments.

1. The name of the file that contains the commit message to be used.
2. The type of commit. This can be message, template, merge, or squash.
3. The SHA-1/hash of a commit (when operating on an existing commit).

In the code below, we’re electing to populate the commit editor workspace with a helpful commit message format reminder prefaced by the name of the current branch.

.git/hooks/prepare-commit-msg

#!/bin/bash

# Result will be output in place of the default commit message on running git commit
current_branch=`git rev-parse --abbrev-ref HEAD`

echo "#$current_branch Commit messages should be of the form [#StoryID:CommitType] Commit Message." > $1

Running git commit will yield the following in the commit text editor

#$main Commit messages should be of the form [#StoryID:CommitType] Commit Message.

We can continue to edit our commit message and exit out of the editor as usual.

commit-msg

This hook is executed after the prepare-commit-msg hook. It can be used to reformat the commit message after it has been input or to validate the message against some checks. For example, it could be used to check for commit message spelling errors or length, before the commit is allowed.

This hook takes one argument, that is the location of the file that holds the commit message.

.git/hooks/commit-msg

#!/bin/bash

# Validates whether commit message is of a certain format.
# Aborts commit if message is unsatisfactory

# Standard commit from Pivotal Tracker [#135316555:Feature]Create Kafka Audit Trail
commit_standard_regex='[#[0-9]{9,}:[a-z]{3,}]:[a-z].+|merge'
error_message="Aborting commit. Please ensure your commit message meets the
               standard requirement. '[#StoryID:CommitType]Commit Message'
              Use '[#135316555:Feature]Create Kafka Audit Trail' for reference"


if ! grep -iqE "$commit_standard_regex" "$1"; then
    echo "$error_message" >&2
    exit 1
fi

In the code above, we’re validating the user-supplied commit message against a standard commit using a regular expression. If the supplied commit does not conform to the regular expression, an error message is directed to the shell’s standard output, the script exits with a status of one, and the commit is aborted.

Go ahead. Create a change and try to make a commit of a form other than [#135316555:Chore]Test commit-msg hook

Git will abort the commit process and give you a handly little tip regarding the format of your commit message.

post-commit

This hook is executed after the commit-msg hook and since the commit has already been made it cannot abort the commit process.

It can however be used to notify the relevant stakeholders that a commit has been made to the remote repository. We could write a post-commit hook, say, to email our project team lead whenever we make a commit to the organization’s remote repository.

In this case, let’s congratulate ourselves on our hard work.

.git/hooks/post-commit

#!/bin/bash

say Congratulations! You\'ve just made a commit! Time for a break.

post-checkout

The post-checkout hook is executed after a successful git checkout is performed. It can be used to conveniently delete temporary files or prepare the checked out development environment by performing installations.

Its exit status does not affect the checkout process.

In the hook below, before checkout to another branch, we’ll pull changes made by others on the remote branch and perform some installation.

.git/hooks/post-checkout

#!/bin/bash

# Executed immediately after a git checkout
repository_name=`basename`git rev-parse --show-toplevel``
current_branch=`git rev-parse --abbrev-ref HEAD`present_working_directory=`pwd`requirements=`ls | grep 'requirements.txt' `echo "Pulling remote branch ....."
git pull origin $current_branch

echo

echo "Installing nodeJS dependencies ....."
npm install

echo

echo "Installing yarn package ....."
npm install yarn
echo "Yarning dependencies ......"
yarn

echo

# Only do this if you find a requirements.txt file at the root of the project
if [ $present_working_directory == $repository_name ] && [ $requirements == 'requirements.txt']; then
  echo "Creating virtual environments for project ......."
  source`which virtualenv`
  echo
  mkvirtualenv $repository_name/$current_branch
  workon $repository_name/$current_branch
  echo "Installing python dependencies ......."
  pip install -r requirements.txt
fi

Don’t forget to make the script executable.

To test the script out, create another branch and check it out like this.

git checkout -b <new-branch>

pre-rebase

This hook is executed before a rebase and can be used to stop the rebase if it is not desirable.

It takes one or two parameters:

1. The upstream repository
2. The branch to be rebased. (This parameter is empty if the rebase is being performed on the current branch)

Let’s outlaw all rebasing on our repository.

.git/hooks/pre-rebase

#!/bin/bash

echo " No rebasing until we grow up. Aborting rebase."
exit 1

Phew! We’ve gone through quite a number of client-side hooks. If you’re still with me, good work!

Persisting hooks

I’ve got some bad news and good news. Which one would you like first?

The bad

The .git/hooks directory is not tagged by version control and so does not persist when we clone a remote repository or when we push changes to a remote repository. This is why we’d earlier stated that local hooks cannot be used to enforce commit policies.

The good

Now before you start sweating, there are a few ways we can get around this.

1. We can use symbolic links or symlinks to link our custom hooks to the ones in the .git/hooks folder.

Create a pre-rebase file in our custom-hooks directory and copy the pre-rebase hook we created in .git/hooks/pre-rebase into it. Next, the rm command removes the pre-rebase hook in .git/hooks:

touch custom-hooks/pre-rebase && cp .git/hooks/pre-rebase custom-hooks/pre-rebase && rm -f .git/hooks/pre-rebase

Next, use the ln command to link the pre-rebase file in custom-hooks to the .git/hooks directory.

# ln -s <source> <target>
ln -s custom-hooks/pre-rebase .git/hooks/pre-rebase

To confirm that the files have been linked, run the following

ls -la .git/hooks

The output for the pre-rebase file should be similar to this:

lrwxr-xr-x   1 emabishi  staff    23B Dec 27 14:57 pre-rebase -> custom-hooks/pre-rebase

Notice the l character prefixing the filesystem file permissions line.

To unlink the two files,

 unlink .git/hooks/pre-rebase

or

rm -f .git/hooks/pre-rebase

1. We can create a directory to store our hooks outside the .git/hooks directory. We’ve already done this by storing our pre-rebase hook in the custom-hooks directory. Like our other files, this folder can be pushed to our remote repository.

Server-Side Hooks

These are hooks that are executed in a remote repository on the triggering of certain events.

Is it clear now? Client-side hooks respond to events on a local repository whilst server-side hooks respond to events triggered on a remote repository.

We’d come across some of them when we listed the files in the .git/hooks directory.

Let’s look at a few of these hooks now.

Order of execution

The server-side hooks we’ll look at here are executed with the following hierarchy.

       <pre-receive>
             |
          <update>
             |
       <post-receive>

pre-receive

This hook is triggered on the remote repository just before the pushed files are updated and can abort the receive process if it exists with a non-zero status.

Since the hook is executed just before the remote is updated, it can be used to enforce commit policies and reject the entire commit if it is deemed unsatisfactory.

update

The update hook is called after the pre-receive hook and functions similarly. The difference is that ii filters each commit ref made to the remote repository independently. It can be used as a fine-tooth comb to reject or accept each ref being pushed.

post-receive

This hook is triggered after an update has been done on the remote repository and so cannot abort the update process. Like the post-commit client-side hook, it can be used to trigger notifications on a successful remote repository update.

In fact, it is more suited for this because a log of the notifications will be stored on a remote server.

Conclusion

We’ve looked at quite a few hooks which should get you up and running. However, I’d love for you to do some more exploration.

For a more comprehensive look at git hooks, I’d like to direct you to:

• The official git guide on hooks
• The git man page on hooks
• The Atlassian git hooks guide

It’s a brave new world out there when it comes to git hooks, so luckily, you don’t always have to write your own custom scripts. You can find a pretty comprehensive list of useful frameworks here.

All the code we’ve written can be found here.