Git Hooks Explained — Automate, Enforce and Protect Your Codebase

#!/usr/bin/env bash
# io.thecodeforge — Explore Git Hooks Directory

# 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

# Step 4: See all available hook trigger points
ls .git/hooks/*.sample | sed 's/.sample$//' | xargs -I {} basename {}
# Output lists every hook Git supports:
# applypatch-msg, commit-msg, post-update, pre-applypatch,
# pre-commit, pre-push, pre-rebase, pre-receive,
# prepare-commit-msg, update

#!/usr/bin/env bash
# io.thecodeforge — 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
#   OR: use core.hooksPath to share with team

set -e  # Exit immediately on any command failure

# 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)$' || true)

# 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.
npx eslint $STAGED_JS_FILES

echo "---"
echo "pre-commit: All checks passed. Proceeding with commit."
exit 0

#!/usr/bin/env bash
# io.thecodeforge — commit-msg hook: enforces Conventional Commits
# 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

set -e  # Exit immediately on any command failure

# 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")

# Strip leading/trailing whitespace and comments (lines starting with #)
COMMIT_MESSAGE_FIRST_LINE=$(echo "$COMMIT_MESSAGE" | head -1 | sed 's/#.*//' | xargs)

# 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.
if ! echo "$COMMIT_MESSAGE_FIRST_LINE" | grep -qE "$CONVENTIONAL_COMMIT_REGEX"; then
  echo ""
  echo "  COMMIT REJECTED — Message does not follow Conventional Commits format."
  echo ""
  echo "  Your message: \"$COMMIT_MESSAGE_FIRST_LINE\""
  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
# io.thecodeforge — pre-receive hook: enforce branch protection on the server
# This hook runs ONCE for the entire push. Reject any non-zero exit.
#
# INSTALLATION: place in the server's .git/hooks/pre-receive
# or configure via Git hosting platform (GitHub branch protection, GitLab push rules)

set -e

# Read each ref being pushed from stdin
# Format: <old-sha> <new-sha> <ref-name>
while read OLD_SHA NEW_SHA REF_NAME; do

  # ─────────────────────────────────────────────
  # RULE 1: Reject direct pushes to main
  # ─────────────────────────────────────────────
  if [ "$REF_NAME" = "refs/heads/main" ]; then
    echo "ERROR: Direct pushes to main are not allowed."
    echo "Please create a pull request instead."
    exit 1
  fi

  # ─────────────────────────────────────────────
  # RULE 2: Reject force-pushes (non-fast-forward)
  # ─────────────────────────────────────────────
  # A force-push is when the new commit is not a descendant of the old commit
  # $OLD_SHA is all zeros for new branches — skip the check in that case
  if [ "$OLD_SHA" != "0000000000000000000000000000000000000000" ]; then
    if ! git merge-base --is-ancestor "$OLD_SHA" "$NEW_SHA" 2>/dev/null; then
      echo "ERROR: Force-push to $REF_NAME rejected."
      echo "Use 'git revert' instead of 'git push --force'."
      exit 1
    fi
  fi

  # ─────────────────────────────────────────────
  # RULE 3: Enforce branch naming convention
  # ─────────────────────────────────────────────
  # Branches must start with: feature/, fix/, hotfix/, release/, chore/
  if ! echo "$REF_NAME" | grep -qE '^refs/heads/(feature|fix|hotfix|release|chore)/'; then
    # Allow main, develop, and staging
    if ! echo "$REF_NAME" | grep -qE '^refs/heads/(main|develop|staging)$'; then
      echo "ERROR: Branch name '$REF_NAME' does not follow naming convention."
      echo "Allowed prefixes: feature/, fix/, hotfix/, release/, chore/"
      echo "Allowed exact names: main, develop, staging"
      exit 1
    fi
  fi

done

# If we reach here, all rules passed.
echo "pre-receive: All checks passed. Push accepted."
exit 0