Himanshu SharmaSoftware engineer
Let’s talk

Git and GitHub · Lesson 27 of 30

Git hooks: running scripts at commit time

Write pre-commit and commit-msg hooks that block mistakes before they enter history, skip them when needed, and share them with a team via core.hooksPath.

13 minPower toolsUpdated 14 November 2026

Awaiting technical review. This lesson is readable but not yet listed in search engines.

By the end of this lessonCreate a working pre-commit and commit-msg hook, explain when hooks run and when they are skipped, and share hooks with a team safely.

What you can do after this lesson

You will write two small hooks, a pre-commit check and a commit-message check, see them stop bad commits, and learn how teams share them. Hooks are a way to attach your own scripts to Git's events. The examples use plain shell scripts and were run in a scratch repository on macOS-style Unix; on Windows, Git Bash runs the same scripts.

What a hook is

When you run git init, Git creates a .git/hooks folder with example files ending in .sample:

bash
ls .git/hooks
text
applypatch-msg.sample
commit-msg.sample
fsmonitor-watchman.sample
post-update.sample

(The list is cut off after four entries.) A hook is a file in that folder with the exact name of an event and no .sample ending, which is executable. Git looks for it at the right moment and runs it. Common events:

Hook Runs Can stop the action?
pre-commit before a commit is created yes, with a non-zero exit
commit-msg after you write the message, with the message file path as an argument yes
pre-push before a push sends anything yes
post-merge after a merge finishes no
post-checkout after switching branches no

The full list and exact arguments are in git help hooks. Hooks can be written in any language that the machine can run: shell, Python, PHP, Node. The first line, such as #!/bin/sh, says which interpreter to use.

A pre-commit hook

Suppose you never want a .env file in a commit. Create .git/hooks/pre-commit with this content and make it executable:

bash
#!/bin/sh
if git diff --cached --name-only | grep -q '\.env$'; then
  echo "pre-commit: refusing to commit a .env file"
  exit 1
fi
bash
chmod +x .git/hooks/pre-commit

The script asks Git which files are staged (git diff --cached --name-only) and exits with 1 if any name ends in .env. Try to commit one:

bash
echo "KEY=1" > .env
git add .env
git commit -m "Add env"
text
pre-commit: refusing to commit a .env file

Git prints your message and aborts: no commit is created. Unstage the file with git restore --staged .env and the next commit goes through. A pre-commit hook that exits 0 (or prints nothing and ends normally) lets the commit proceed:

text
[main (root-commit) e9b1cc2] Add a
 1 file changed, 1 insertion(+)
 create mode 100644 a.txt

The exit status is the whole contract: zero means carry on, anything else means stop. Pre-commit is a good place for fast checks such as syntax checks, a formatter, or scanning for obvious secrets. Run only what finishes in a second or two; slow hooks train people to bypass them.

A commit-msg hook

commit-msg receives one argument, the path of the file containing the message, so it can validate or even edit it. This one rejects subject lines longer than 72 characters:

bash
#!/bin/sh
first=$(head -n 1 "$1")
if [ ${#first} -gt 72 ]; then
  echo "commit-msg: first line is longer than 72 characters"
  exit 1
fi

After saving it as .git/hooks/commit-msg and running chmod +x, a very long subject is refused:

text
commit-msg: first line is longer than 72 characters

while git commit -m "Add b" succeeds as before. This enforces the message conventions from the commit messages lesson automatically. A small caution: ${#first} is shell syntax available in sh on most systems; test your hook on the shells your team uses.

Skipping hooks

git commit --no-verify bypasses pre-commit and commit-msg:

bash
git commit --no-verify -m "Skip the checks"
text
[main 9b844cf] Skip the checks
 1 file changed, 1 insertion(+)
 create mode 100644 c.txt

That is by design: sometimes you need to commit a work-in-progress snapshot. It also means client-side hooks cannot be used to enforce policy. Anyone can skip them. Real enforcement belongs on the server, for example through branch protection and required checks, which the Actions lesson touches on.

Sharing hooks with a team

Hooks live in .git, which git clone does not copy, so a new teammate gets none of them. The usual fix is to keep the scripts in a normal tracked folder and tell Git to use it:

bash
mkdir .githooks
cp .git/hooks/pre-commit .githooks/
git config core.hooksPath .githooks
git config --get core.hooksPath
text
.githooks

Commit the .githooks folder. Each teammate runs the git config core.hooksPath .githooks command once after cloning, and it is worth putting that step in the README. Many projects use helper tools to install hooks automatically. Because hooks run code on your machine, read any hook in a repository you clone from someone else before enabling it: a hook is a script that Git will execute for you.

Other uses

Hooks can run a quick test suite before a push (pre-push), install dependencies after a pull (post-merge), or reject commits to main locally. Server-side hooks, such as pre-receive, run on the remote and can enforce rules for everyone, but hosting services like GitHub do not let ordinary users install them, and offer protection rules instead.

Common mistakes

  • Forgetting chmod +x. Git ignores a hook that is not executable.
  • Leaving .sample in the name. Samples never run.
  • Slow hooks. They slow every commit and people start using --no-verify.
  • Expecting teammates to have your hooks. Share them through core.hooksPath.
  • Treating hooks as security. They can be skipped.

Exercise

  1. Write a pre-commit hook that refuses to commit any file ending in .log, and test it.
  2. Write a commit-msg hook that requires the subject to be at least ten characters.
  3. Commit with --no-verify to see that both are bypassed.
Show one possible answer
bash
#!/bin/sh
if git diff --cached --name-only | grep -q '\.log$'; then
  echo "pre-commit: no log files, please"
  exit 1
fi

Save as .git/hooks/pre-commit. For the second hook:

bash
#!/bin/sh
first=$(head -n 1 "$1")
if [ ${#first} -lt 10 ]; then
  echo "commit-msg: subject must be at least 10 characters"
  exit 1
fi

Run chmod +x on both. git add debug.log && git commit -m "Add a log file for debugging" is refused by the first hook; git commit --no-verify goes through.

Next: GitHub Actions at a glance: automation on every push.

Key points

  • A hook is an executable script in .git/hooks whose name tells Git when to run it, such as pre-commit or commit-msg.
  • If a pre-commit or commit-msg hook exits with a non-zero status, Git aborts the commit.
  • Hooks live in .git, so they are not copied by git clone; share them with a tracked folder and core.hooksPath.
  • git commit --no-verify skips pre-commit and commit-msg hooks, so hooks are a convenience, not a security control.
  • Keep hooks fast and predictable; heavy checks belong in automated builds on the server.

Check yourself

1. A pre-commit hook script exits with status 1. What does Git do?
2. Why does a new teammate not get your hooks when they clone the repository?
3. What does git commit --no-verify do?
4. Which hook receives the path to the file holding the commit message?