Improve Your Team‘s Development Workflow with Githooks

As a software team scales, it becomes increasingly important to standardize development practices to ensure everyone is working in a consistent way. While style guides and code reviews help, even with the best of intentions, it‘s easy for things to slip through the cracks. Busy engineers may forget to run the linter, or someone might push code with a commit message that doesn‘t match your team‘s convention.

This is where Githooks come in. Githooks are a built-in Git feature that allow you to automatically trigger custom scripts when certain Git events occur, like commits, merges, and pushes. This makes them a powerful tool for catching issues early, automating repetitive tasks, and enforcing standards and best practices across your development team.

In this post, we‘ll dive into what makes Githooks so useful and look at some examples of Githooks you can add to your team‘s workflow today. By the end, you‘ll see why Githooks are an invaluable addition to any development team‘s toolbox.

How Githooks Work

Githooks work by hooking into various events in the Git lifecycle, such as:

• post-checkout
• pre-commit
• prepare-commit-msg
• commit-msg
• post-commit
• post-merge
• pre-push

When one of these events is triggered, Git looks for a corresponding script in the repo‘s .git/hooks directory and executes it. These hook scripts can be written in any language, as long as they are executable on the system.

For example, say your team requires all commit messages to be formatted a certain way, like feat: Add new login form. You could add a commit-msg hook that checks the message against a regular expression and blocks the commit if it doesn‘t match:

#!/bin/sh

commit_msg_file="$1"
commit_msg=$(cat "$commit_msg_file")

if ! [[ "$commit_msg" =~ ^(feat|fix|docs|style|refactor|test|chore)(\(.+?\))?: .{1,50} ]]; then
    echo "Invalid commit message format. Use feat|fix|docs|style|refactor|test|chore followed by a short description."
    exit 1
fi

Now, any time a developer tries to make a commit with an invalid message format, their commit will be rejected and they will see a descriptive error message telling them how to fix it.

With a few well-placed Git hooks, many common issues can be caught automatically before they make it into the codebase. Let‘s look at a few more examples of useful Githooks.

Useful Githooks for Any Team

Here are a few Githooks that pretty much any development team can benefit from adding to their workflow:

Post-Checkout Hook for Branch Naming

If your team uses a branch naming convention like feat/add-login-form, a post-checkout hook can validate new branch names and prevent misspellings or deviations from the standard.

#!/bin/sh

branch=$(git rev-parse --abbrev-ref HEAD)

if ! [[ "$branch" =~ ^(feat|fix|docs|style|refactor|test|chore)/[a-z0-9-]+$ ]]; then
    echo "Invalid branch name. Use feat|fix|docs|style|refactor|test|chore followed by a short description."
    exit 1
fi

Commit Message Hook for Formatting

A commit-msg hook is useful for enforcing commit message conventions, like the example we saw earlier. You could get even fancier and require messages to reference Jira ticket numbers too.

Pre-Push Hook for Linting and Tests

Pre-push is a good place to put tasks you want to run before code gets pushed to a remote branch, like linting, formatting and running tests. That way, you maintain a high quality bar for any code that makes it to your remote repo.

#!/bin/sh

npm run lint
npm run test

if [ $? -ne 0 ]; then
 echo "Linting or tests failed. Fix errors before pushing."
 exit 1
fi

Making Githooks Required

For Githooks to be effective, it‘s important that everyone on the team uses them. The best way to do this is include your Githooks in the project setup and onboarding steps.

Make sure to document what each hook does and how to troubleshoot if issues arise. For convenience, you can add your hooks in a githooks directory and symlink them to .git/hooks as part of your onboarding script.

It‘s also crucial that your Githook scripts are executable. You can ensure this by running chmod +x on the hook files.

For larger teams, you may want to look into tools that help manage Git hooks across many developers and projects, like Husky or Overcommit. These make it easier to share hooks via Git and ensure all team members have them enabled.

Troubleshooting Common Githook Issues

Even with a well-implemented set of Githooks, issues can still arise. Here are a couple common problems and how to resolve them:

Githook Not Executing

If your Githook doesn‘t seem to be running, first make sure the hook script is executable. If it‘s in the right location (.git/hooks) and has execute permissions but still isn‘t triggering, double check that the Git event is firing as expected.

Githook Blocking Commits or Pushes

On the flip side, an overly aggressive Githook can be frustrating and slow down development by blocking commits or pushes.

If devs frequently run into false positives from a linter or other hook check, see if you can refine the rules or add exceptions for the problematic cases. Make sure your hook scripts provide actionable error messages so it‘s clear to the developer what they need to fix.

Githooks: A Valuable Tool for Any Dev Team

Githooks provide a convenient way to define and share small bits of process across your development team. By using hooks to automate enforcement of team conventions, you save mental overhead, avoid issues making it to code review, and keep your codebase squeaky clean.

While Githooks take some up-front work to configure, the payoff in improved efficiency and standardization makes them well worth it for any team. Give them a try and see how much smoother your development process can be! Your team will thank you.