Git Hooks Explained — Automate, Enforce and Protect Your Codebase

#!/usr/bin/env bash

# Step 1: Initialise a fresh repo so we can explore its structure
git init my-demo-project
cd my-demo-project

# Step 2: List the hooks directory — every repo has this out of the box
ls -la .git/hooks

# Step 3: Look at one of the sample files to understand the structure
# Git ships these as *.sample so they don't accidentally run
cat .git/hooks/pre-commit.sample

#!/usr/bin/env bash
# pre-commit hook: runs ESLint on staged JS/TS files only
# so developers get instant feedback without linting the whole project.
#
# HOW TO INSTALL:
#   cp this file to .git/hooks/pre-commit
#   chmod +x .git/hooks/pre-commit

# Collect only the JS and TS files that are staged (index), not all tracked files.
# --diff-filter=ACM means: Added, Copied, or Modified — skips Deleted files.
STAGED_JS_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(js|ts|jsx|tsx)$')

# If no relevant files are staged, there's nothing to lint — exit cleanly.
if [ -z "$STAGED_JS_FILES" ]; then
  echo "pre-commit: No JS/TS files staged. Skipping lint check."
  exit 0  # Exit code 0 = success, Git continues with the commit
fi

echo "pre-commit: Running ESLint on staged files..."
echo "---"

# Run ESLint only against the files we collected above.
# --no-eslintrc is omitted intentionally — we want the project config to apply.
npx eslint $STAGED_JS_FILES

# Capture ESLint's exit code immediately after it runs.
ESLINT_EXIT_CODE=$?

if [ $ESLINT_EXIT_CODE -ne 0 ]; then
  echo "---"
  echo "pre-commit: ESLint found errors. Commit aborted."
  echo "Fix the issues above, then stage your changes again with 'git add'."
  exit 1  # Non-zero exit code = failure, Git CANCELS the commit
fi

echo "---"
echo "pre-commit: All checks passed. Proceeding with commit."
exit 0  # Explicit success — Git creates the commit

#!/usr/bin/env bash
# commit-msg hook: enforces the Conventional Commits specification.
# Format: <type>(<optional scope>): <description>
# Examples:
#   feat(auth): add OAuth2 login support
#   fix: prevent crash when user list is empty
#   chore(deps): update lodash to 4.17.21

# Git passes the PATH to the temporary file containing the commit message
# as the first argument ($1). We must read from that file — not from stdin.
COMMIT_MESSAGE_FILE="$1"
COMMIT_MESSAGE=$(cat "$COMMIT_MESSAGE_FILE")

# Define the Conventional Commits regex pattern.
# Allowed types: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
# The scope (in parentheses) is optional.
# The description must be at least 10 characters to avoid messages like "fix: stuff"
CONVENTIONAL_COMMIT_REGEX="^(feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert)(\([a-zA-Z0-9_-]+\))?: .{10,}$"

# Test the commit message against our pattern.
# The -E flag enables extended regex in grep.
if ! echo "$COMMIT_MESSAGE" | grep -qE "$CONVENTIONAL_COMMIT_REGEX"; then
  echo ""
  echo "  ✖ COMMIT REJECTED — Message does not follow Conventional Commits format."
  echo ""
  echo "  Your message: \"$COMMIT_MESSAGE\""
  echo ""
  echo "  Required format:"
  echo "    <type>(<optional scope>): <description — at least 10 characters>"
  echo ""
  echo "  Valid types: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert"
  echo ""
  echo "  Examples:"
  echo "    feat(payments): add Stripe webhook handler"
  echo "    fix: resolve null pointer in user session lookup"
  echo "    chore: update Node.js to v20 in CI workflow"
  echo ""
  exit 1  # Reject the commit — Git discards it entirely
fi

# If we reach here, the message is valid.
echo "  ✔ Commit message format validated."
exit 0

#!/usr/bin/env bash
# This script demonstrates BOTH approaches to sharing Git hooks with a team.
# Pick ONE for your project — don't use both simultaneously.

# ─────────────────────────────────────────────
# APPROACH 1: Git's core.hooksPath (language-agnostic)
# ─────────────────────────────────────────────

# Create a 'hooks' directory at the project root (this WILL be committed to git)
mkdir -p hooks

# Copy your hook scripts into this directory
# (We'll write a simple pre-commit as an example)
cat > hooks/pre-commit << 'EOF'
#!/usr/bin/env bash
echo "[shared hook] Running pre-commit checks..."
# Add your lint/test commands here
exit 0
EOF

# Make the hook executable — git won't run non-executable scripts
chmod +x hooks/pre-commit

# Tell git to look in our committed 'hooks' folder instead of .git/hooks
# Each developer runs this ONCE after cloning the repo
git config core.hooksPath hooks

echo "Git hooks path set to: $(git config core.hooksPath)"

# Commit the hooks directory so the team gets it
git add hooks/
git commit -m "chore: add shared git hooks via core.hooksPath"

# ─────────────────────────────────────────────
# APPROACH 2: Husky (JavaScript / Node.js projects)
# ─────────────────────────────────────────────

# Install husky as a dev dependency
npm install --save-dev husky

# Initialise husky — creates .husky/ directory and adds 'prepare' script to package.json
# The 'prepare' script runs automatically on 'npm install', so every developer
# who clones the repo and runs 'npm install' gets the hooks automatically.
npx husky init

# Create a pre-commit hook via husky
echo "npx lint-staged" > .husky/pre-commit

# Husky hooks are real files in .husky/ — commit them
git add .husky/
git commit -m "chore: configure husky pre-commit hook with lint-staged"

echo ""
echo "Setup complete. Every developer who runs 'npm install' will now have the hooks active."