Git Hooks

Table of Contents

Introduction

Git hooks are scripts that Git executes before or after events such as: commit, push, and receive. They allow you to customize Git's internal behavior and trigger customizable actions at key points in the development lifecycle. These powerful tools can help enforce development standards, automate tasks, and ensure code quality throughout your project.

By leveraging Git hooks, development teams can implement automated checks, validations, and processes that run at specific points in the Git workflow. This automation helps maintain consistency, reduce errors, and streamline the development process across the entire team.

Types of Git Hooks

Git hooks can be categorized into two main types: client-side hooks and server-side hooks. Each type serves different purposes and runs at different stages of the Git workflow.

Client-Side Hooks

  • pre-commit: Runs before a commit is created, useful for code quality checks
  • prepare-commit-msg: Runs before the commit message editor is fired up
  • commit-msg: Used to validate project or commit message conventions
  • post-commit: Runs after a commit is created, often used for notifications
  • pre-push: Runs before a push is executed, great for running tests

Server-Side Hooks

  • pre-receive: Runs when receiving pushed commits before any refs are updated
  • update: Similar to pre-receive but runs once for each ref being updated
  • post-receive: Runs after all refs have been updated, commonly used for deployments

Client-side hooks run on the developer's local machine and are ideal for providing immediate feedback before changes are shared with others. Server-side hooks run on the Git server and are perfect for enforcing project-wide policies and performing actions after code has been pushed.

Implementing Git Hooks

Git hooks are stored in the .git/hooks directory of every Git repository. They are shell scripts that must be named properly (without any extension) to match the hook type, made executable (chmod +x), and written in a script language the system can execute (bash, python, etc.).

Example: Simple Pre-commit Hook

#!/bin/sh
# Pre-commit hook to check for debugging statements

if git diff --cached | grep -i "debugger"
then
    echo "Error: Debugging statement(s) found"
    exit 1
fi

This simple pre-commit hook checks for debugging statements in your code before allowing a commit. If it finds any instances of debugger, it will prevent the commit and display an error message. This helps ensure that debugging code doesn't accidentally make it into your repository.

Best Practices

When implementing Git hooks, following these best practices will help ensure they are effective, maintainable, and don't hinder the development process.

  • Keep hooks fast and lightweight to avoid slowing down Git operations
  • Include hooks in version control by storing them in a separate directory and symlinking
  • Document hook requirements and setup processes in the project README
  • Make hooks configurable when possible
  • Include appropriate error messages and exit codes

Common Use Cases

  • Code formatting and linting
  • Running unit tests before pushes
  • Checking commit message formats
  • Preventing commits to protected branches
  • Automated deployment after successful pushes

Using Git Hooks to Avoid CI Costs

Git hooks can be strategically used to reduce CI/CD costs by running important checks locally before code reaches your CI pipeline. By implementing pre-commit and pre-push hooks that validate code quality, run tests, and perform security checks, you can catch issues early and avoid unnecessary CI builds that would consume paid compute time.

Risks of Local-Only Validation

While using Git hooks for local validation can save CI costs, relying solely on client-side hooks carries significant risks:

  • Hook bypassing: Developers can skip pre-commit or pre-push hooks using flags like --no-verify
  • Inconsistent environments: Local development environments may differ from production
  • Security concerns: Critical security checks should always run in a controlled CI environment

Therefore, while Git hooks are valuable for early feedback and cost reduction, they should complement rather than replace CI/CD pipeline validations. Critical checks should still be enforced at the CI level to ensure consistency and security.

Husky: Git Hooks Made Easy

Husky is a popular tool that makes Git hooks easier to manage and share across development teams. It allows you to configure Git hooks using package.json and ensures hooks are shared among all developers working on a project.

Key Features of Husky

  • Easy setup: Simple installation and configuration through npm
  • Package.json integration: Hooks can be defined directly in your project's package.json
  • Cross-platform compatibility: Works consistently across different operating systems
  • Automatic hook installation: Hooks are automatically set up when installing project dependencies

Setting Up Husky

npm install husky --save-dev
npx husky install

Add this to your package.json:

{
  "scripts": {
    "prepare": "husky install"
  },
  "husky": {
    "hooks": {
      "pre-commit": "npm test",
      "pre-push": "npm run build"
    }
  }
}

Common Husky Configurations

  • Lint-staged integration: Run linters on staged files only
  • Commit message validation: Enforce commit message conventions
  • Test execution: Run tests before pushing code
  • Code formatting: Automatically format code before commits

Conclusion

Git hooks provide a powerful mechanism for automating tasks and enforcing standards throughout the development workflow. By implementing appropriate hooks at both the client and server levels, teams can improve code quality, maintain consistency, and streamline their development processes.

While tools like Husky make Git hooks more accessible and shareable, it's important to use them judiciously and in conjunction with CI/CD pipelines for critical validations. When implemented thoughtfully, Git hooks become an invaluable part of a robust development workflow, helping teams deliver higher quality code more efficiently.