Maintaining consistent code quality across a team can feel like an endless battle—especially when developers are spread across different time zones, IDEs, and personal workflows. Enter Git hooks: tiny scripts that run at key points in the Git lifecycle. By embedding linting, formatting, and testing directly into the commit process, you can catch style violations, security flaws, and failing tests before they ever touch the shared repository. This guide walks you through setting up client‑side and server‑side hooks, wiring them into popular tools, and avoiding the common traps that turn a helpful guardrail into a frustrating bottleneck.
What You’ll Need
- A local Git repository (any language or framework)
- Basic familiarity with Bash or PowerShell scripting
- Linters/formatters for your stack (e.g., ESLint, Prettier, flake8, Black)
- Optional: Access to a Git server that supports server‑side hooks (GitHub, GitLab, Bitbucket self‑hosted, or a bare repo on SSH)
- Node.js, Python, or any runtime required by your chosen tools
Step 1: Choose the Right Hook Type
Git provides dozens of hook points, but for code‑quality enforcement the most common are pre-commit, commit-msg, and pre‑push. pre-commit runs before a commit is created, making it ideal for linting and formatting. commit-msg validates the commit message itself (think Conventional Commits). pre‑push runs on the client just before data is sent to a remote, allowing you to run a test suite that would be too heavy for pre‑commit. Decide which hooks align with your team’s workflow and start with one; you can always add more later.
Step 2: Create a Shared Hook Template
To keep every developer on the same page, store hook scripts in version control. Create a directory called .githooks at the root of your project and add a README.md explaining each script. For example, a simple pre-commit script for a JavaScript project might look like this:
#!/usr/bin/env bash
# .githooks/pre-commit
# Run ESLint and Prettier, abort commit on failures
# Install dependencies if missing (optional)
if ! command -v eslint &>/dev/null; then
echo "ESLint not found, installing locally..."
npm install --silent
fi
# Run linters
echo "Running ESLint..."
npx eslint . --max-warnings=0
if [ $? -ne 0 ]; then
echo "ESLint errors detected. Fix them before committing."
exit 1
fi
echo "Running Prettier..."
npx prettier --check .
if [ $? -ne 0 ]; then
echo "Code is not formatted. Run 'npx prettier --write .' and retry."
exit 1
fi
exit 0
Make the script executable (chmod +x .githooks/pre-commit) and commit the .githooks folder.
Step 3: Wire the Template into Each Clone
Git does not automatically copy custom hooks from the repository; you need to tell each clone to use them. The most portable way is to add a small snippet to the repository’s .git/config via a setup script:
#!/usr/bin/env bash
# setup-hooks.sh – run once after cloning
git config core.hooksPath .githooks
echo "Git hooks path set to .githooks"
Ask every team member to run ./setup-hooks.sh after cloning, or add it as an npm/yarn script ("postinstall": "./setup-hooks.sh") so it runs automatically when dependencies are installed.
Step 4: Enforce Commit Message Standards (Optional but Recommended)
A clean commit history is as important as clean code. Use a commit-msg hook to enforce Conventional Commits, for example:
#!/usr/bin/env node
// .githooks/commit-msg
const fs = require('fs');
const msgPath = process.argv[2];
const msg = fs.readFileSync(msgPath, 'utf8').trim();
const pattern = /^(feat|fix|docs|style|refactor|test|chore)((.*))?: .{1,72}$/;
if (!pattern.test(msg)) {
console.error('nInvalid commit message format.');
console.error('Expected: type(scope?): short description');
process.exit(1);
}
process.exit(0);
Again, make it executable (chmod +x .githooks/commit-msg). Now any commit that doesn’t match the pattern will be rejected, nudging developers toward a consistent log.
Step 5: Add a Pre‑Push Hook for Heavy Checks
Running a full test suite on every pre‑commit can slow developers down. Instead, use pre‑push to run integration tests, security scans, or build steps that take longer than a second. Here’s a Python‑centric example that runs pytest and fails the push on any error:
#!/usr/bin/env bash
# .githooks/pre-push
# Run pytest; abort push if tests fail
echo "Running test suite..."
pytest
if [ $? -ne 0 ]; then
echo "Tests failed – push aborted. Fix the issues and try again."
exit 1
fi
# Optional: run bandit for security scanning
if command -v bandit &>/dev/null; then
echo "Running Bandit security scan..."
bandit -r .
if [ $? -ne 0 ]; then
echo "Security issues detected – push aborted."
exit 1
fi
fi
exit 0
Remember to install any required tools in your CI pipeline as well; hooks are a first line of defense, not a replacement for server‑side validation.
Step 6: (Optional) Enforce Hooks Server‑Side
Client‑side hooks can be bypassed—developers might run git commit --no-verify or simply forget to set up the hook path. To guarantee enforcement, add a server‑side pre‑receive or update hook on your bare repository. A minimal pre‑receive script that re‑runs the client‑side pre‑commit checks looks like this:
#!/usr/bin/env bash
# /srv/git/myproject.git/hooks/pre-receive
while read oldrev newrev refname; do
# Get list of new commits
commits=$(git rev-list $oldrev..$newrev)
for commit in $commits; do
# Extract the tree and run linting on the snapshot
git checkout $commit -- . &>/dev/null
./setup-hooks.sh # ensure hooks are available on the server
.githooks/pre-commit || exit 1
done
done
exit 0
On hosted platforms like GitHub or GitLab, you can achieve the same effect with protected branch rules and CI pipelines that fail on lint errors, but a custom pre‑receive hook gives you full control for on‑prem installations.
Common Mistakes to Avoid
1 Hard‑coding absolute paths. Hooks run on any machine, so use relative paths (e.g., ./node_modules/.bin/eslint) or rely on npx to locate binaries.
2 Making hooks too slow. A pre‑commit that takes >5 seconds will frustrate developers and encourage them to skip verification. Keep checks lightweight; offload heavy tasks to pre‑push or CI.
3 Ignoring exit codes. Forgetting exit 1 after a failed lint will let bad code slip through.
4 Not version‑controlling the hook scripts. If a new team member clones the repo without the .githooks folder, they lose the guardrails.
5 Using git commit --no-verify as a habit. Educate the team on why bypassing hooks is dangerous, and consider repository policies that reject pushes containing commits made with --no-verify.
Tips and Tricks
Cache dependencies. In CI or on the server, cache node_modules or venv directories to keep hook execution fast.
Parallelize linting. Tools like eslint -f unix . | parallel --gnu -j4 can speed up large codebases.
Provide friendly output. Use colors (printf 'e[31mErrore[0m') and clear instructions so developers know exactly how to fix a failure.
Combine with commitizen. Pair a commit-msg hook with commitizen to auto‑populate a properly formatted message.
Document the hook lifecycle. Add a .githooks/README.md that explains when each hook runs and why, reducing confusion for new contributors.
Frequently Asked Questions
Can I use Git hooks with Windows developers?
Yes. Write hooks in a cross‑platform language (Node.js, Python, or PowerShell) and use a shebang that works on both Unix and Windows (#!/usr/bin/env node for Node scripts). Git for Windows respects the core.hooksPath setting, and you can ship .cmd wrappers if needed.
What if a developer disables a hook on purpose?
The safest mitigation is a server‑side pre‑receive hook or CI job that repeats the same checks. If a push fails the server hook, the developer must fix the issue locally, effectively preventing the bypass.
How do I keep hook scripts from becoming outdated?
Treat the .githooks directory like any other source code: bump the version in package.json or requirements.txt, run npm install or pip install -r requirements.txt as part of the setup-hooks.sh script, and document breaking changes in the repo’s CHANGELOG.
Conclusion
Git hooks are a low‑maintenance, high‑impact way to bake code‑quality standards directly into the developer workflow. By storing hook scripts in version control, configuring core.hooksPath, and layering lightweight pre‑commit checks with heavier pre‑push or server‑side validation, you create a safety net that catches style violations, insecure code, and failing tests before they pollute the shared codebase. Remember to keep the scripts fast, well‑documented, and versioned, and your team will appreciate the invisible guardian that lets them focus on building, not fixing preventable errors.
Photo by Fer Troulik on Unsplash
