Understanding Git Hooks

Git hooks are Git’s native mechanism for triggering custom scripts before or after core repository operations such as commit, merge, push, and checkout. Think of them as Git’s plugin system — lightweight, portable, and entirely under your control.

Every Git repository contains a .git/hooks directory populated with example hook scripts. To activate a hook, rename the relevant example file (removing its .sample extension), make it executable, and add your logic. The Git documentation covers installation in detail.

Client-Side vs. Server-Side Hooks

Hooks fall into two broad categories:

• Client-side hooks run on a developer’s local workstation and affect local operations like committing and checking out branches.
• Server-side hooks run on the remote Git host (e.g., Bitbucket Server, GitLab, or GitHub Enterprise) and can gate pushes and merges centrally across the whole team.

Pre-Receive vs. Post-Receive Hooks

Hooks are also classified by when they fire relative to the triggering operation:

• Pre-receive (pre-) hooks run before an operation completes. Crucially, they can exit with a non-zero status to cancel the operation entirely — making them ideal for enforcing quality gates.
• Post-receive (post-) hooks run after an operation has already completed and cannot cancel it. They are well-suited for automation tasks like sending notifications or triggering deployments.

Common tasks automated with Git hooks include:

• Validating that a commit message references the correct issue tracker key (e.g., a Jira ticket)
• Enforcing merge preconditions such as passing tests or minimum code coverage
• Posting build or merge notifications to a team chat channel
• Configuring the workspace automatically when switching branches

Hook 1: Enforce Clean Builds Before Merging to Main

Developers are generally diligent, but it is easy to forget to check the CI status on a branch — especially when multiple contributors are pushing changes concurrently. A server-side pre-receive hook closes this gap by making the check automatic and mandatory.

The hook inspects incoming push operations targeting the main (or master) branch. When it detects a merge, it queries the CI server for the latest build result on the source branch. If any tests are failing, the hook exits with a non-zero code, rejecting the push and printing a message explaining why.

A reference implementation by Atlassian’s Tim Petterson, designed to work with Bamboo CI, is available on Bitbucket. The script is intentionally straightforward to customise for other CI servers such as Jenkins or CircleCI — the key integration point is an API call to retrieve the latest build status for a given branch and revision.

How It Works in Practice

1. A developer runs git push origin feature/my-branch and opens a pull request to merge into main.
2. On push (or on merge attempt, depending on your server configuration), the pre-receive hook fires.
3. The hook script calls the CI server’s API to retrieve the build status for the branch’s HEAD revision.
4. If the build is red (failing tests), the push is rejected with a descriptive error message.
5. If the build is green, the push proceeds normally.

Hook 2: Protect Hard-Earned Code Coverage

Teams that have invested significant effort in retroactively adding test coverage to a legacy codebase know how painful it is to watch that coverage percentage erode as new features ship without accompanying tests. A pre-receive server-side hook can enforce a coverage floor on the main branch.

This hook also intercepts incoming merges to main. It then performs two lookups against the CI server:

1. Current coverage on main — the baseline the incoming branch must meet or exceed.
2. Coverage on the feature branch — pulled from the build associated with the commit being merged.

If the branch’s coverage is lower than main’s, the merge is rejected.

Prerequisites and Configuration

Because most CI servers do not expose code coverage metrics through a standard remote API, the script fetches the coverage report directly as a build artifact. This requires that your build pipeline is configured to publish the coverage report as a shared artifact on every build — for both the main branch and feature branches.

The reference implementation targets Bamboo and Clover (Atlassian’s code coverage tool for Java and Groovy). It can be adapted for other tool combinations — the essential requirement is that your CI server makes coverage report artifacts accessible via a predictable URL or API endpoint.

Important: This hook does not generate code coverage. It only reads coverage data that your existing build process already produces. If your builds do not measure coverage today, you will need to add that to your pipeline first.

Hook 3: Surface Branch Build Status at Checkout

Because friends don’t let friends check out broken branches.

This is a client-side post-checkout hook. Unlike the server-side hooks above, it runs on each developer’s local workstation and fires automatically whenever they switch branches with git checkout (or git switch).

What the Hook Does

1. After git checkout completes, the script reads the HEAD revision of the newly checked-out branch from the local repository.
2. It queries the CI server to determine whether that revision has been built — and if so, whether the build passed or failed.
3. The result is printed directly in the terminal alongside the normal checkout output.

Two Practical Scenarios

Creating a new feature branch from main: The hook tells you immediately whether the HEAD of main built successfully, confirming it is a safe and stable starting point for new work.

Detecting a stale local copy: If the hook reports a failed build for a revision but the team’s CI dashboard shows a green build for that branch, your local copy is behind. You can then decide whether to git pull before continuing.

This hook is the lowest-friction option to introduce to a team. It requires no server-side configuration, no repository admin access, and no changes to the shared workflow — each developer installs it independently in their local .git/hooks directory.

Tooling and Portability

The three hooks described above were originally written to target Bamboo (build server), Clover (code coverage), and Bitbucket (Git hosting). However, Git hooks themselves are vendor-neutral — they are simply executable scripts in a well-known directory. The CI-specific logic in any hook script is limited to a handful of HTTP API calls or artifact URL patterns, which can be swapped out for equivalent calls to Jenkins, GitHub Actions, GitLab CI, CircleCI, or any other system that exposes build and coverage status via HTTP.

If you work in a polyglot environment or want to manage hooks consistently across a team, tools such as pre-commit or Husky can help version-control and distribute client-side hooks alongside your project code.

Summary

Git hooks are one of the most underutilised features in a CI/CD toolkit. Introducing even one of these hooks can measurably reduce the number of broken builds that reach your main branch — and the post-checkout hook in particular pays dividends immediately with zero team coordination required.

Background: Why Git Hooks Matter After an SVN Migration

Switching a team’s primary code repository from SVN to Git brings considerable freedom — but also new responsibilities. One powerful mechanism Git provides is hooks: executable scripts placed in the .git/hooks directory (or your_repo.git/hooks for a bare repository) that run automatically at specific points in the Git workflow. Hooks can write output to the console during a push or commit, and can even abort those operations entirely.

Common use cases for hooks on a central (bare) repository include:

• Preventing large binary files from being pushed into the repository.
• Enforcing a commit-message naming convention (e.g., requiring an issue tracker ID).
• Blocking pushes to protected branches without passing CI checks.

The hook covered in depth here is the update hook, which is the right tool for enforcing rules on a central shared repository.

Understanding the Update Hook

The update hook fires on the server side every time someone pushes to a repository. It runs once per ref being updated, meaning a push that updates three branches will invoke the hook three times.

Git passes three positional arguments to the hook:

1. The ref name being updated — for example, refs/heads/my_fancy_branch.
2. The old object SHA-1 — the commit currently at the tip of that ref in the remote repository.
3. The new object SHA-1 — the commit at the tip of the ref in the developer’s local repository.

Exit with a non-zero status to reject the push; exit with zero to accept it. Because the hook runs before branch labels are updated, you can inspect exactly which commits are new without worrying about race conditions with other pushes.

The Naive Approach — and Why It Falls Apart

The most obvious implementation iterates over every commit between $old_ref and $new_ref and checks each one individually:

# Pseudo-code — do not copy verbatim
commits=$(git rev-list $old_ref..$new_ref)

for commit in $commits; do
    if ! check_commit "$commit"; then
        echo "Commit $commit failed the check."
        exit 1
    fi
done

This works in simple cases but has three serious problems:

1. Slow per-commit overhead. Each call to check_commit typically spawns one or more subprocesses (e.g., grep, awk, git cat-file). Process-spawn overhead accumulates quickly across hundreds of commits.
2. Early exit hides multiple problems. The script exits on the first bad commit. Developers must fix issues one at a time and re-push repeatedly before they see all violations — a frustrating experience.
3. Merge commits inflate the revision range. git rev-list $old_ref..$new_ref returns all reachable commits, including those pulled in from master via a merge. Those commits were already validated when they landed on master; re-checking them wastes time and can push hook execution into the minutes range on long-running feature branches.

The Merge-Inflation Problem Illustrated

Consider this common workflow:

• Developer works on feature_branch.
• Developer merges master into feature_branch to stay current.
• Developer adds a few more commits on feature_branch.
• Developer pushes.

The naive rev-list call returns every commit reachable from $new_ref but not from $old_ref — including potentially hundreds of commits that came from master. On a busy repository, a feature branch delayed by a few weeks could drag hook execution to several minutes per push. That is unacceptable for developer experience.

The Smarter Approach

Two goals drive the improved design:

1. Skip commits that are already reachable from existing branches (i.e., already verified).
2. Validate all remaining commits in a single pipeline rather than one at a time.

Filtering Already-Known Commits

The key insight is that the update hook runs after all new objects have been received but before any branch labels are moved. That means existing branch labels still point to where they were before the push. You can exploit this to exclude any commit reachable from a known branch:

git rev-list $old_ref..$new_ref --not --branches='*'

The --not --branches='*' flag tells Git to exclude any commit reachable from any local branch ref. Because branch labels haven’t moved yet, this effectively limits the output to commits that are genuinely new to the repository — exactly the set that needs checking.

Processing Commits in One Pipeline

Instead of looping and spawning a process per commit, pipe the entire set of new commits through a sequence of Git and Unix commands in one shot. Collect all violations at once, report them all, and then exit with a failure code if any exist. Developers see all problems in a single push attempt.

Practical Example 1: Block Oversized Files

Large binary files committed to a Git repository cause repository bloat that is painful to undo. Here is an efficient pipeline to detect and reject them:

# Step 1: list SHA1 hashes and paths of all objects touched by new commits
git rev-list --objects $old_ref..$new_ref --not --branches='*' \

# Step 2: for each object, print its SHA1, size in bytes, and path
  | git cat-file --batch-check='%(objectname) %(objectsize) %(rest)' \

# Step 3: filter objects exceeding the size limit, remove duplicates
  | awk -v limit="$FILESIZE_LIMIT_BYTES" '$2 > limit { print }' \
  | sort \
  | uniq --skip-fields=2

The output is a list of SHA1 size path triplets for every oversized object. If the output is non-empty, print a helpful message listing each offending file and its size, then exit 1 to reject the push.

Why this is fast: git cat-file --batch-check reads all objects in a single pass without checking out file contents. The entire pipeline runs in roughly constant time relative to the number of commits, not file sizes.

Practical Example 2: Enforce Commit-Message Format

If your team requires every commit message to reference an issue tracker ID (e.g., PROJ-1234), the following pipeline validates all new commits in one pass:

# List SHA1 and subject line for non-merge commits only
git log --no-merges --pretty='%H %s' $old_ref..$new_ref --not --branches='*' \

# Filter out commits whose subject line matches the required pattern
  | grep -Ev "$MESSAGE_REGEX"

Any line remaining after the grep -Ev filter represents a commit that violates the naming convention. Collect the output, print the offending commit hashes and subjects as a single error block, and exit 1 only after showing everything. This way developers can fix all non-conforming messages in one go before re-pushing.

Note: The --no-merges flag skips merge commits, which typically have auto-generated messages that do not follow the team convention.

Edge Cases to Handle

The examples above cover the common push case. Real-world hooks also need to handle:

• New branch creation: $old_ref will be the null SHA-1 (0000000000000000000000000000000000000000). Your script must detect this and adjust the rev-list range accordingly — otherwise the range is invalid.
• Branch deletion: $new_ref will be the null SHA-1. There are no commits to check; just allow or deny based on policy.
• Force pushes: The old and new refs may not share a common ancestor. Consider whether your checks should still apply and how your rev-list range behaves.
• Tags: The ref name will start with refs/tags/ rather than refs/heads/. Decide whether your hook logic applies to tag objects.

General Principles for Hook Performance

• Prefer batch operations over per-commit loops. Unix pipelines and Git’s built-in batch modes (--batch-check, --pretty format strings) are far more efficient than spawning a subprocess per commit.
• Report all violations before exiting. Collect every problem, display them all at once, then exit. Never make developers push multiple times just to discover new errors.
• Exclude already-verified commits. Use --not --branches='*' to avoid re-checking work that is already on an accepted branch.
• Keep hooks focused. One hook file can chain multiple checks, but each check should be independently understandable and testable.
• Test hooks locally before deploying. Hooks can be copied into a local .git/hooks directory and invoked manually with representative SHA-1 arguments.

Conclusion

Git’s update hook is a powerful enforcement point on a central repository, but a naïve per-commit loop can turn every push into a slow, frustrating experience. By using --not --branches='*' to skip already-accepted commits and processing the remaining set in a single pipeline, you can enforce rules like file-size limits and commit-message conventions in a matter of seconds. The result is a hook infrastructure that protects code quality without getting in developers’ way.