-
- Joined
- Mar 22, 2026
-
- Messages
- 292
-
- Reaction score
- 0
-
- Points
- 0
Git hooks are powerful, customizable scripts that Git executes automatically before or after events like committing, pushing, or merging. They allow developers to automate various tasks, enforce project standards, and integrate with external tools, significantly enhancing development workflows.
What are Git Hooks?
At their core, Git hooks are simply executable scripts (usually shell scripts, but can be in any language with an interpreter) located in the
There are two main categories of hooks:
1. Client-side hooks: These run on the developer's local machine and are triggered by operations like committing and merging. They are useful for enforcing local policies, preparing commit messages, or running tests before a push.
2. Server-side hooks: These run on the Git server and are triggered by network operations like receiving pushed commits. They are crucial for enforcing project-wide policies, integrating with CI/CD systems, and ensuring code quality before integration into the main codebase.
This article will focus primarily on client-side hooks, as they are most commonly used for local workflow automation.
Common Client-Side Hooks and Their Uses
Here are some of the most frequently used client-side hooks:
Anatomy of a Hook Script
A Git hook is just an executable file with a specific name in the
Here's a basic example of a
Explanation:
Practical Examples
1. Enforcing Code Style with
Using a linter like ESLint or a formatter like Prettier is common. A
This hook automatically formats and lints staged files, and if ESLint finds unfixable errors, it prevents the commit. The
2. Auto-installing Dependencies with
After merging a branch (especially a feature branch that might introduce new dependencies), you often need to run
Sharing Git Hooks Across a Team
The biggest challenge with client-side hooks is that they are local to each repository and *not* committed with the project's
Several strategies exist for sharing hooks:
1. Manual Copying: Instruct team members to copy hook scripts from a designated directory (e.g.,
2. Symlinks: Create a script that symlinks project-specific hooks (e.g., from
3.
* Create a directory for your shared hooks, e.g.,
* Place your hook scripts (e.g.,
* Tell Git to use this path:
* Add
Now, anyone who clones the repo and runs
Best Practices and Considerations
Git hooks are an indispensable tool for maintaining code quality, enforcing standards, and streamlining development workflows. By leveraging them effectively, teams can build more robust and consistent projects.
What are Git Hooks?
At their core, Git hooks are simply executable scripts (usually shell scripts, but can be in any language with an interpreter) located in the
.git/hooks directory of your repository. When you initialize a new Git repository, Git populates this directory with example hook scripts (e.g., pre-commit.sample, post-merge.sample). These sample files are inactive until you remove the .sample extension, making them executable by Git.There are two main categories of hooks:
1. Client-side hooks: These run on the developer's local machine and are triggered by operations like committing and merging. They are useful for enforcing local policies, preparing commit messages, or running tests before a push.
2. Server-side hooks: These run on the Git server and are triggered by network operations like receiving pushed commits. They are crucial for enforcing project-wide policies, integrating with CI/CD systems, and ensuring code quality before integration into the main codebase.
This article will focus primarily on client-side hooks, as they are most commonly used for local workflow automation.
Common Client-Side Hooks and Their Uses
Here are some of the most frequently used client-side hooks:
pre-commit: Runs *before* a commit is created. This is ideal for linting code, running unit tests, checking for common errors (like debug statements), or formatting code to ensure consistency. If this hook exits with a non-zero status, the commit is aborted.prepare-commit-msg: Runs *after thepre-commithook, but before* a commit message editor is launched. It's used to programmatically generate or modify the default commit message.commit-msg: Runs *after* the user has entered a commit message. It allows you to validate the commit message format, ensuring it adheres to project guidelines (e.g., Jira ticket numbers, conventional commits). Aborts the commit if it exits non-zero.post-commit: Runs *after* a commit is successfully created. Useful for notification systems, logging, or updating external issue trackers. It doesn't affect the commit itself.pre-rebase: Runs *before* a rebase operation. Can be used to prevent rebasing on certain branches or ensure the rebase is safe.post-checkout: Runs *after* you switch branches or restore files. Useful for updating project dependencies (e.g.,npm install), cleaning up temporary files, or triggering environment setup scripts.post-merge: Similar topost-checkout, but specifically runs *after* a successfulgit mergecommand. Ideal for rebuilding project assets, running tests, or updating dependencies.pre-push: Runs *before*git pushattempts to transfer objects to a remote repository. This is a critical hook for running final tests, ensuring all commits are valid, or preventing pushes to protected branches. Exiting non-zero aborts the push.
Anatomy of a Hook Script
A Git hook is just an executable file with a specific name in the
.git/hooks/ directory. For example, pre-commit is the script that runs before a commit.Here's a basic example of a
pre-commit hook that checks for a specific string in staged files:
Bash:
#!/bin/sh
# This hook prevents committing files that contain "debugger;" or "console.log"
if git rev-parse --verify HEAD >/dev/null 2>&1
then
against=HEAD
else
# Initial commit: diff against an empty tree
against=$(git hash-object -t tree /dev/null)
fi
# Check staged files for unwanted patterns
if git diff --cached --name-only --diff-filter=ACM "$against" | grep -E '\.(js|ts|py|php)$' | xargs grep -lE '(debugger;|console\.log)'
then
echo "ERROR: Found 'debugger;' or 'console.log' in staged files. Aborting commit."
exit 1
fi
exit 0Explanation:
#!/bin/sh: Shebang line, specifying the interpreter.git rev-parse --verify HEAD: Checks if there's an existing HEAD (i.e., not the very first commit).git diff --cached --name-only --diff-filter=ACM "$against": Gets the names of all added, copied, or modified (ACM) files that are currently staged.grep -E '\.(js|ts|py|php)$': Filters for specific file extensions.xargs grep -lE '(debugger;|console\.log)': For each filtered file, searches for the patternsdebugger;orconsole.log. The-lflag lists filenames where a match is found.exit 1: If matches are found, the script exits with a non-zero status, aborting the commit.exit 0: If no issues, the script exits with zero, allowing the commit to proceed.
Practical Examples
1. Enforcing Code Style with
pre-commitUsing a linter like ESLint or a formatter like Prettier is common. A
pre-commit hook can ensure all staged JavaScript/TypeScript files are formatted and linted before committing.
Bash:
#!/bin/sh
# Stash uncommitted changes (not staged) to avoid linting them
git stash --keep-index --include-untracked > /dev/null 2>&1
# Run Prettier on staged files
echo "Running Prettier..."
npx prettier --write $(git diff --cached --name-only --diff-filter=ACM | grep '\.js[x]?$\|\.ts[x]?$\|\.css$\|\.json$')
# Run ESLint on staged files
echo "Running ESLint..."
if ! npx eslint --fix $(git diff --cached --name-only --diff-filter=ACM | grep '\.js[x]?$\|\.ts[x]?$'); then
echo "ESLint found errors. Please fix them before committing."
git stash pop > /dev/null 2>&1 # Restore stashed changes
exit 1
fi
# Re-add any files modified by Prettier/ESLint --fix
git add $(git diff --name-only --diff-filter=M)
# Pop the stash back
git stash pop > /dev/null 2>&1
exit 0git stash commands are crucial to ensure only staged changes are processed and unstaged changes aren't lost.2. Auto-installing Dependencies with
post-mergeAfter merging a branch (especially a feature branch that might introduce new dependencies), you often need to run
npm install, composer install, or pip install. A post-merge hook can automate this.
Bash:
#!/bin/sh
# Check if package.json (or equivalent) was changed
if git diff --name-only HEAD@{1} HEAD | grep -q 'package.json'; then
echo "package.json changed. Running npm install..."
npm install
fi
# You could add similar checks for yarn.lock, composer.json, requirements.txt, etc.
# if git diff --name-only HEAD@{1} HEAD | grep -q 'composer.json'; then
# echo "composer.json changed. Running composer install..."
# composer install
# fi
exit 0HEAD@{1} refers to the state of HEAD before the merge, allowing us to compare changes to package.json.Sharing Git Hooks Across a Team
The biggest challenge with client-side hooks is that they are local to each repository and *not* committed with the project's
.git directory. This means they aren't automatically shared when you clone a repository.Several strategies exist for sharing hooks:
1. Manual Copying: Instruct team members to copy hook scripts from a designated directory (e.g.,
scripts/git-hooks/) into their .git/hooks/ directory. This is error-prone.2. Symlinks: Create a script that symlinks project-specific hooks (e.g., from
_hooks/) into .git/hooks/. This is better but still requires manual setup or a setup script.3.
core.hooksPath (Git 2.9+): This is the most robust method. You can configure Git to look for hooks in a directory *within* your project, which can then be committed to the repository.* Create a directory for your shared hooks, e.g.,
githooks/.* Place your hook scripts (e.g.,
githooks/pre-commit) in this directory.* Tell Git to use this path:
git config core.hooksPath githooks* Add
githooks/ to your repository and commit it.Now, anyone who clones the repo and runs
git config core.hooksPath githooks will automatically use the shared hooks. This command can be added to a project's setup script.Best Practices and Considerations
- Keep Hooks Fast: Slow hooks can frustrate developers and hinder productivity. If a hook takes too long, consider moving its functionality to a CI/CD pipeline.
- Handle Errors Gracefully: Provide clear error messages if a hook fails, explaining why the operation was aborted and how to fix it.
- Make Hooks Idempotent: Ensure running a hook multiple times has the same effect as running it once.
- Allow Bypassing (with caution): Sometimes, a developer might need to bypass a hook (e.g., to commit a work-in-progress fix). For
pre-commit,commit-msg, andpre-rebase, you can use the--no-verify(or-n) flag:git commit -m "WIP" --no-verify. Use this sparingly. - Don't Rely Solely on Client-Side Hooks for Critical Enforcement: Client-side hooks can be easily bypassed. For critical policies (e.g., security checks, mandatory tests), always duplicate enforcement on the server-side (e.g., with
pre-receiveorupdatehooks, or through a CI/CD system).
Git hooks are an indispensable tool for maintaining code quality, enforcing standards, and streamlining development workflows. By leveraging them effectively, teams can build more robust and consistent projects.