Skip to content

Git Hooks

Automating workflows with Git hooks — pre-commit, pre-push, and commit-msg scripts.

What you'll learn

  • What Git hooks are and where they live
  • Common hooks: pre-commit, pre-push, commit-msg
  • Writing hook scripts to enforce quality standards
  • Using hook frameworks like Husky and pre-commit

Concept

What Are Git Hooks?

Git hooks are scripts that Git executes automatically at specific points in the Git workflow. They let you enforce code quality, run tests, format code, and prevent bad commits — all without manual intervention.

Hooks live in the .git/hooks/ directory of every repository. They are shell scripts (or any executable) that run when the corresponding Git event occurs.

ls .git/hooks/
# pre-commit.sample
# pre-push.sample
# commit-msg.sample
# ...

The .sample files are examples. To activate a hook, remove the .sample extension and make the script executable.

Common Hooks

pre-commit

Runs before a commit is created. Use it to:

  • Run linters and formatters
  • Check for debug code (console.log, print)
  • Validate file sizes
  • Exit non-zero to block the commit
# .git/hooks/pre-commit
#!/bin/sh
# Run the linter
npm run lint
if [ $? -ne 0 ]; then
  echo "Linting failed. Commit blocked."
  exit 1
fi

pre-push

Runs before a push to the remote. Use it to:

  • Run the full test suite
  • Check that the branch is up to date
  • Exit non-zero to block the push
# .git/hooks/pre-push
#!/bin/sh
# Run tests before pushing
npm test
if [ $? -ne 0 ]; then
  echo "Tests failed. Push blocked."
  exit 1
fi

commit-msg

Runs after the commit message is written. Use it to:

  • Enforce commit message conventions (Conventional Commits)
  • Check message length
  • Exit non-zero to reject the message
# .git/hooks/commit-msg
#!/bin/sh
# Enforce Conventional Commits format
pattern="^(feat|fix|docs|style|refactor|test|chore): .+"
if ! grep -qP "$pattern" "$1"; then
  echo "Commit message must follow Conventional Commits: 'type: message'"
  exit 1
fi

Other Useful Hooks

  • pre-merge-commit — runs before a merge commit is created
  • post-commit — runs after a commit (e.g., notifications)
  • pre-rebase — runs before a rebase (can block it)
  • prepare-commit-msg — modify the commit message before the editor opens (e.g., add branch name)

The Problem with Native Hooks

Native hooks in .git/hooks/ have a problem: they are not version-controlled. The .git folder is not committed, so hooks are not shared with your team. Each developer must set them up manually.

Hook Frameworks

To solve this, use a hook framework that installs hooks from a config file in your repository:

Husky (JavaScript/Node projects)

npm install --save-dev husky
npx husky init

Create hooks in the husky/ directory:

# husky/pre-commit
npm run lint

Configure in package.json or .huskyrc:

{
  "husky": {
    "hooks": {
      "pre-commit": "npm run lint",
      "pre-push": "npm test"
    }
  }
}

pre-commit (Python/multi-language)

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
  - repo: https://github.com/pycqa/flake8
    rev: 7.0.0
    hooks:
      - id: flake8

Install with pip install pre-commit and run pre-commit install.

Best Practices for Hooks

  • Keep hooks fast — developers run them on every commit. If they take 30 seconds, people will bypass them.
  • Make hooks informative — clear error messages explain what failed and how to fix it.
  • Auto-fix when possible — run formatters that fix code, not just linters that report problems.
  • Do not block on style nits in pre-commit — use CI for thorough checks; hooks should catch only critical issues.
  • Document your hooks — so new team members understand what is being enforced.

Example

              # --- Set up a native pre-commit hook ---
cd .git/hooks
cp pre-commit.sample pre-commit
chmod +x pre-commit

# Write the hook script
cat > pre-commit << 'EOF'
#!/bin/sh
# Block commits with console.log statements
if git diff --cached | grep -q "console.log"; then
  echo "ERROR: Remove console.log before committing."
  echo "Found in:"
  git diff --cached --name-only | xargs grep -l "console.log"
  exit 1
fi

# Run the linter
npm run lint
EOF

# --- Set up a commit-msg hook for Conventional Commits ---
cat > .git/hooks/commit-msg << 'EOF'
#!/bin/sh
pattern="^(feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert)(\(.+\))?: .+"
if ! grep -qP "$pattern" "$1"; then
  echo "Commit message must follow Conventional Commits format:"
  echo "  type(scope): description"
  echo "Types: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert"
  exit 1
fi
EOF
chmod +x .git/hooks/commit-msg

# --- Set up Husky (Node.js project) ---
npm install --save-dev husky lint-staged
npx husky init
echo "npm run lint" > .husky/pre-commit
echo "npm test" > .husky/pre-push

# package.json lint-staged config:
# "lint-staged": {
#   "*.{js,ts}": ["eslint --fix", "prettier --write"]
# }

# --- Set up pre-commit framework (Python project) ---
pip install pre-commit
cat > .pre-commit-config.yaml << 'EOF'
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-added-large-files
EOF
pre-commit install

# --- List available hooks ---
ls .git/hooks/*.sample
            

Shows setting up native pre-commit and commit-msg hooks, using Husky for Node.js projects with lint-staged, and the pre-commit framework for Python/multi-language projects. The commit-msg hook enforces Conventional Commits format. Hook frameworks solve the problem of sharing hooks with your team.

Try it

Common mistakes

The mistake

Writing hooks that are too slow and developers start bypassing them with --no-verify

The fix

Keep pre-commit hooks under a few seconds. Run only fast checks (lint, format) in pre-commit; run slow checks (full test suite) in pre-push or CI. If a hook takes 30 seconds, developers will use git commit --no-verify to bypass it, defeating the purpose. Use lint-staged to run checks only on changed files.

The mistake

Setting up hooks in .git/hooks/ and expecting them to be shared with the team

The fix

The .git directory is not version-controlled, so native hooks are not shared. Use a hook framework like Husky (Node.js) or pre-commit (Python) that stores hook config in your repository. Team members run one install command to set up all hooks. Document the setup in your README.

Related Cheatsheets

Practice Git Hooks

1 exercise

Practice Git Hooks

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors