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 createdpost-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
- CI/CD YAML Generator
Hooks run locally; CI runs in the cloud — generate both for defense in depth.
- .gitignore Generator
Keep hook dependencies and config files properly ignored or committed.
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 Resources
Related Cheatsheets
- Git Cheatsheet
Git hooks list and common hook scripts.
Practice Git Hooks
1 exercise
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.