Git Hooks

Open source on GitHub.
Made with by Matthew Hudson

Introduction

Git Hooks are a built-in feature of Git that allow developers to automate tasks and enforce policies throughout the Git workflow. By writing custom scripts that Git can execute at key points in the development process, Git Hooks enable developers to streamline their workflow, ensure code quality, and enforce project-specific policies. In this guide, we will explore Git Hooks and show you how to use them effectively.

What are Git Hooks?

Git Hooks are scripts that Git can execute automatically when certain events occur, such as before or after a commit, push, or merge. There are several types of Git Hooks, each with a specific purpose. Pre-commit hooks, for example, can be used to enforce code formatting or run tests before a commit is made. Pre-push hooks can be used to prevent pushes to certain branches or run additional tests before pushing. Post-merge hooks can be used to perform actions after a merge is completed, such as updating dependencies or generating documentation.

These hook scripts are only limited by a developer's imagination. Some example hook scripts include:

  • pre-commit: Check the commit message for spelling errors.
  • pre-receive: Enforce project coding standards.
  • post-commit: Email/SMS team members of a new commit.
  • post-receive: Push the code to production.

How to Use Git Hooks:

To use Git Hooks, you simply need to create executable scripts in the .git/hooks directory of your Git repository. The scripts should be named after the Git Hook event they correspond to (e.g., pre-commit, pre-push, post-merge) and have the appropriate permissions (chmod +x). Once the scripts are in place, Git will automatically execute them at the corresponding events.

Sharing Hooks

By default, Git hooks reside in the .git/hooks directory of your repository. However, this directory is not tracked by Git and is not committed to the repository. To share hooks across a team, you can use the core.hooksPath configuration (introduced in Git 2.9).

  1. Create a directory to store your versioned hooks (e.g., .githooks).
  2. Move your hook scripts into that directory and commit them.
  3. Configure Git to use this directory: git config core.hooksPath .githooks

Many of the projects listed below can automate this process for you.

Here's a full list of hooks you can attach scripts to:

Hook Description
applypatch-msg Validates the commit message file for patches from git am.
pre-applypatch Runs after a patch is applied but before a commit is made.
post-applypatch Runs after a patch is applied and a commit is made.
pre-commit Runs before a commit is created. Used for linting, testing, and formatting checks.
pre-merge-commit Runs after a merge is successful but before a merge commit is created.
prepare-commit-msg Runs after the default commit message is created but before the editor is started.
commit-msg Validates the commit message after it has been edited. Useful for enforcing message standards.
post-commit Runs after a commit is made. Useful for notifications or logging.
pre-rebase Runs before a rebase starts. Can be used to prevent rebasing of protected branches.
post-checkout Runs after a git checkout or git switch. Useful for setting up the environment.
post-merge Runs after a successful git merge or git pull.
pre-receive Runs on the server before references are updated. Can be used to enforce push policies.
update Runs on the server once for each ref being updated.
post-receive Runs on the server after all references have been updated.
post-update Runs on the server after refs are updated, often used for git update-server-info.
pre-auto-gc Runs before an automatic garbage collection.
post-rewrite Runs after commands that rewrite commits (e.g., amend, rebase).
pre-push Runs before a git push starts. Can be used to prevent pushing to certain remotes.

Tips for Writing Effective Git Hooks:

When writing Git Hooks, it's important to keep a few things in mind:

  1. Git Hooks should be fast and reliable. Slow or unreliable scripts can slow down the Git workflow and cause errors.
  2. Git Hooks should be well-documented. Make sure to include comments in your scripts so that other developers can understand what they do.
  3. Git Hooks should be non-intrusive. Avoid scripts that modify code or files without the user's consent.

Conclusion

Git Hooks are a powerful tool for automating tasks and enforcing policies in Git. By writing custom scripts that Git can execute at key points in the development process, developers can streamline their workflow and ensure code quality. With the tips and techniques outlined in this guide, you'll be able to use Git Hooks effectively in your own projects.

Reading

Projects

  • overcommit - A well-maintained, up-to-date, flexible Git hook manager.
  • Lolcommits - Takes a snapshot with your webcam every time you git commit code, and archives a lolcat style image with it.
  • podmena - Enhance your commit messages adding random emoji to it.
  • pre-commit - A framework for managing and maintaining multi-language pre-commit hooks.
  • Hooks is a command line git hook management tool.
  • Git Build Hook Maven Plugin - A maven plugin for managing client side (local) git configuration and installing hooks for those working on your project.
  • Git::Hooks - A framework for implementing Git (and Gerrit) hooks.
  • git-pre-commit-hook - Hook that blocks bad commits. Useful for Python-development.
  • App::GitHooks - A modular and easy to configure git hooks framework, supporting many plugins.
  • Jig - A pre-commit hook on steroids.
  • GitPHPHooks - Write your hooks in PHP, manage and organize them on a task and project level. Has an additional Hooks library on GitHub.
  • Grunt GitHooks - Setup, manage and update your hooks with Grunt. Can be used with all languages, supports templates.
  • git-hooks - Hook manager.
  • node-git-hooks - Automated, cross-platform, deployment-friendly Git hooks installation.
  • Husky - Git hooks made easy. Popular choice for Node.js projects.
  • lint-staged - Run linters against staged git files and don't let 💩 slip into your code base!
  • ghks - A simple, dependency-free Git hook manager for any language.
  • git-hooks-php - Git hooks for PHP based projects.
  • commandbox-githooks - Git hooks for CommandBox CFML based projects.
  • Autohook - A very, very small Git hook manager with focus on automation.
  • autohooks - A library for managing and writing git hooks in Python.
  • hooks4git - A simple, flexible and language agnostic git hook management approach.
  • Githooks - Auto-install Git hook, that supports hooks in any language checked into Git and also shared repos.
  • Awesome Git Hooks - A collection of awesome Git Hooks.
  • ghooks - Simple git hooks for Javascript. Manage your hooks via package.json.
  • ghooks.cr - Simple git hooks for Crystal. Keep your hooks in a versioned ".githooks/" directory.
  • ghooks.gradle - Simple git hooks for Gradle. Keep your hooks in a versioned ".githooks/" directory.
  • Lefthook - Fast and powerful Git hooks manager for any type of project.
  • Git Hooks List - List of Git hooks.
  • .githooker - Eases setup, maintenance, handling of git-hooks across teams/projects for virtually all languages + common git-hook-ish tasks as declarative configuration inside your repo!
  • Commit lint - Commitlint helps your team adhere to a commit convention.
  • git-precommit-checks - Configurable checks for staged contents.
  • validate-branch-name - Branch name validator.
  • Semantic release - Fully automated version management and package publishing.

Snippets

  • Prevent Direct Push to Master - A pre-push hook that prevents direct code push to master branch and notify with a message in Amazon Chime group.

Contribute

If you have a Git Hook you love, or a resource you've written for the community - please create a pull request here.