- Joined
- Mar 22, 2026
- Messages
- 218
- Reaction score
- 0
Windows 10
Google Chrome 147
Git is an indispensable tool for version control, but its power extends beyond just tracking changes and merging branches. Git hooks allow developers to execute custom scripts automatically at specific points in the Git workflow, enabling powerful automation, policy enforcement, and integration with external tools. Understanding and utilizing Git hooks can significantly streamline development processes and improve code quality.
What are Git Hooks?
Git hooks are simply scripts that Git executes before or after events like committing, pushing, or receiving pushed commits. They reside in the
Client-Side vs. Server-Side Hooks
Git hooks are broadly categorized into two types:
1. Client-Side Hooks: These run on the developer's local machine. They are typically used for local repository actions like committing and merging. Examples include validating commit messages, running linters before a commit, or preventing commits to certain branches.
2. Server-Side Hooks: These run on the remote Git server. They are primarily used to enforce repository policies, integrate with CI/CD pipelines, and perform actions after a push. Examples include ensuring all commits pass tests before being accepted, notifying external systems of new pushes, or updating project management tools.
Common Client-Side Hooks
These hooks are crucial for maintaining code quality and consistency within your local workflow:
* Purpose: This is one of the most frequently used hooks. It's ideal for running automated checks on staged content before the commit is finalized. If the script exits with a non-zero status, Git aborts the commit.
* Use cases: Linting code, running unit tests, formatting code (e.g., Prettier, Black), checking for trailing whitespace, ensuring required files exist.
* Example (Shell script to check for large files):
* Purpose: Allows you to programmatically edit the default commit message.
* Use cases: Pre-populating commit messages with branch names, issue tracker IDs, or template text.
* Purpose: Validates the commit message content. If the script exits with a non-zero status, Git aborts the commit.
* Use cases: Enforcing commit message conventions (e.g., conventional commits, requiring a Jira ticket ID), checking message length.
* Example (Shell script to check for a JIRA ticket ID):
* Purpose: Used for notification or non-altering actions. It cannot change the outcome of the commit.
* Use cases: Triggering an automated build, updating a changelog, notifying a chat system, or running a local script to clean up temporary files.
Common Server-Side Hooks
These hooks are essential for maintaining repository integrity and integrating with your CI/CD pipeline:
* Purpose: Allows you to enforce project-wide policies. If the script exits with a non-zero status, the entire push is rejected.
* Use cases: Preventing pushes to
* Purpose: Provides more granular control than
* Use cases: Preventing fast-forward merges on certain branches, enforcing specific branch naming conventions, ensuring that only authorized users can push to certain branches.
* Purpose: Used for notification and integration with external systems. It cannot reject a push.
* Use cases: Triggering CI/CD pipelines (e.g., Jenkins, GitLab CI, GitHub Actions), sending email notifications to team members, updating a project's website, integrating with issue trackers.
* Example (Shell script to trigger a CI/CD build):
Implementing Git Hooks
1. Locate the hooks directory: Navigate to
2. Rename/Create a hook script:
* To use an example, remove the
* To create a new hook, simply create a new file with the hook's name (e.g.,
3. Make it executable: On Linux/macOS, use
4. Write your script: Git hooks are typically shell scripts, but you can use any scripting language (Python, Ruby, Node.js) as long as the shebang line (
Best Practices and Considerations
* Use a Git submodule for common hooks.
* Utilize tools like Husky (for Node.js projects) that manage hooks via
Git hooks are a powerful, often underutilized feature that can significantly enhance your team's development workflow. By automating mundane tasks and enforcing project policies, you can reduce errors, improve code quality, and free up developers to focus on building features. Experiment with them to find out how they can best serve your specific project needs.
What are Git Hooks?
Git hooks are simply scripts that Git executes before or after events like committing, pushing, or receiving pushed commits. They reside in the
.git/hooks directory of every Git repository. By default, this directory contains example scripts (ending with .sample) that demonstrate their functionality. To enable a hook, you just need to remove the .sample extension and ensure the script is executable.Client-Side vs. Server-Side Hooks
Git hooks are broadly categorized into two types:
1. Client-Side Hooks: These run on the developer's local machine. They are typically used for local repository actions like committing and merging. Examples include validating commit messages, running linters before a commit, or preventing commits to certain branches.
2. Server-Side Hooks: These run on the remote Git server. They are primarily used to enforce repository policies, integrate with CI/CD pipelines, and perform actions after a push. Examples include ensuring all commits pass tests before being accepted, notifying external systems of new pushes, or updating project management tools.
Common Client-Side Hooks
These hooks are crucial for maintaining code quality and consistency within your local workflow:
pre-commit:
* Purpose: This is one of the most frequently used hooks. It's ideal for running automated checks on staged content before the commit is finalized. If the script exits with a non-zero status, Git aborts the commit.
* Use cases: Linting code, running unit tests, formatting code (e.g., Prettier, Black), checking for trailing whitespace, ensuring required files exist.
* Example (Shell script to check for large files):
Code:
bash
#!/bin/sh
# .git/hooks/pre-commit
MAX_FILE_SIZE_KB=1024 # 1MB
for file in $(git diff --cached --name-only); do
if [ -f "$file" ]; then
size_kb=$(du -k "$file" | cut -f1)
if [ "$size_kb" -gt "$MAX_FILE_SIZE_KB" ]; then
echo "Error: File '$file' is too large (${size_kb}KB). Max allowed is ${MAX_FILE_SIZE_KB}KB."
exit 1
fi
fi
done
exit 0
prepare-commit-msg:
* Purpose: Allows you to programmatically edit the default commit message.
* Use cases: Pre-populating commit messages with branch names, issue tracker IDs, or template text.
commit-msg:
* Purpose: Validates the commit message content. If the script exits with a non-zero status, Git aborts the commit.
* Use cases: Enforcing commit message conventions (e.g., conventional commits, requiring a Jira ticket ID), checking message length.
* Example (Shell script to check for a JIRA ticket ID):
Code:
bash
#!/bin/sh
# .git/hooks/commit-msg
COMMIT_MSG_FILE=$1
if ! grep -qE '^(feat|fix|docs|style|refactor|test|chore|build|ci|perf)\(.+\): .*' "$COMMIT_MSG_FILE"; then
echo "Error: Commit message does not follow Conventional Commits spec."
echo "Example: 'feat(scope): add new feature'"
exit 1
fi
exit 0
post-commit:
* Purpose: Used for notification or non-altering actions. It cannot change the outcome of the commit.
* Use cases: Triggering an automated build, updating a changelog, notifying a chat system, or running a local script to clean up temporary files.
Common Server-Side Hooks
These hooks are essential for maintaining repository integrity and integrating with your CI/CD pipeline:
pre-receive:
git push is received.* Purpose: Allows you to enforce project-wide policies. If the script exits with a non-zero status, the entire push is rejected.
* Use cases: Preventing pushes to
master/main directly, ensuring all pushed commits are signed, checking for specific commit message patterns across all pushed commits, validating pushed content for sensitive information.update:
pre-receive, but runs once for each reference (branch/tag) being updated by the push.* Purpose: Provides more granular control than
pre-receive. It receives arguments representing the reference name, old object name, and new object name. If any update script fails, only that specific reference update is rejected, not the entire push.* Use cases: Preventing fast-forward merges on certain branches, enforcing specific branch naming conventions, ensuring that only authorized users can push to certain branches.
post-receive:
* Purpose: Used for notification and integration with external systems. It cannot reject a push.
* Use cases: Triggering CI/CD pipelines (e.g., Jenkins, GitLab CI, GitHub Actions), sending email notifications to team members, updating a project's website, integrating with issue trackers.
* Example (Shell script to trigger a CI/CD build):
Code:
bash
#!/bin/sh
# .git/hooks/post-receive
# Read stdin to get oldref, newref, refname
while read oldrev newrev refname; do
# Example: Trigger a Jenkins build on 'main' branch push
if [ "$refname" = "refs/heads/main" ]; then
echo "Push to main detected. Triggering CI build..."
# Replace with actual CI trigger URL and credentials
curl -X POST "https://your-ci-server.com/job/your-project/buildWithParameters?token=YOUR_TOKEN&branch=$refname"
fi
done
exit 0
Implementing Git Hooks
1. Locate the hooks directory: Navigate to
.git/hooks within your repository.2. Rename/Create a hook script:
* To use an example, remove the
.sample extension (e.g., pre-commit.sample becomes pre-commit).* To create a new hook, simply create a new file with the hook's name (e.g.,
post-receive).3. Make it executable: On Linux/macOS, use
chmod +x .git/hooks/your-hook-name.4. Write your script: Git hooks are typically shell scripts, but you can use any scripting language (Python, Ruby, Node.js) as long as the shebang line (
#!) points to the correct interpreter and the script is executable.Best Practices and Considerations
- Sharing Hooks: Hooks are not committed with your repository by default. To share hooks across a team, you can:
scripts/githooks) and use git config core.hooksPath scripts/githooks to point Git to this directory.* Use a Git submodule for common hooks.
* Utilize tools like Husky (for Node.js projects) that manage hooks via
package.json.- Error Handling: Ensure your scripts handle errors gracefully and provide clear feedback to the user or logs.
- Performance: Keep client-side hooks fast. Slow hooks can frustrate developers and hinder productivity.
- Security (Server-Side): Server-side hooks run with the permissions of the Git server user. Be cautious about what operations they perform and ensure they are secure.
- Testing: Test your hooks thoroughly, especially server-side ones, in a staging environment before deploying to production.
Git hooks are a powerful, often underutilized feature that can significantly enhance your team's development workflow. By automating mundane tasks and enforcing project policies, you can reduce errors, improve code quality, and free up developers to focus on building features. Experiment with them to find out how they can best serve your specific project needs.
