name	install-git-hooks
description	Install pre-commit hooks to automatically lint markdown files before commits
group	git
author	@tnez
version	1.0.0
keywords	["git","hooks","automation","linting"]

Runbook: Install Git Hooks

Purpose: Install pre-commit hooks to automatically lint markdown files before commits Owner: Development Team Last Updated: 2025-10-20 Frequency: One-time setup per developer environment

Overview

This runbook provides the procedure for installing git hooks in your local docent repository. Git hooks automatically run quality checks before committing, helping catch markdown linting errors early in the development process.

Script Reference: ../../scripts/install-git-hooks.sh

Expected duration: 1-2 minutes

What this accomplishes:

Installs pre-commit hook that runs markdown linting on staged .md files
Prevents commits with markdown linting errors
Provides early feedback before CI/CD runs

Note: This is optional but recommended for all developers.

Prerequisites

Required Tools

git - Version control system
npm - Node.js package manager
Project dependencies installed (npm install)

Required Access

Write access to local .git/hooks directory (standard for any git repository)

Pre-Flight Checklist

Before starting, ensure:

You are in the docent project root directory
Git repository is initialized (.git directory exists)
Project dependencies are installed: ls node_modules/markdownlint-cli2
You can write to .git/hooks: ls -ld .git/hooks

Procedure

Step 1: Verify Location

Purpose: Ensure you're in the correct directory

Commands:

# Verify you're in the docent project root
pwd
# Expected: /Users/tnez/Code/tnez/docent (or your path to docent)

# Verify git repository exists
ls -d .git
# Expected: .git

# Verify hooks directory exists
ls -d .git/hooks
# Expected: .git/hooks

Validation:

You're in the project root
.git directory exists
.git/hooks directory exists

If step fails:

Navigate to project root: cd /path/to/docent
If .git doesn't exist: git init or clone the repository again

Step 2: Run Installation Script

Purpose: Install the pre-commit hook

Commands:

# Run the installation script
scripts/install-git-hooks.sh

# Expected output:
# Installing pre-commit hook...
# ✓ Git hooks installed successfully
#
# The pre-commit hook will now run markdown linting on staged .md files.
# To bypass the hook, use: git commit --no-verify
#
# To uninstall, run: rm .git/hooks/pre-commit

Validation:

Script completes successfully with ✓ message
No error messages displayed
Exit code is 0

If step fails:

Error: "Not in a git repository root directory"
- Navigate to project root and retry
- Verify .git directory exists
Error: "Permission denied"
- Check file permissions: ls -l scripts/install-git-hooks.sh
- Make executable if needed: chmod +x scripts/install-git-hooks.sh
Error: "No such file or directory"
- Verify hook source exists: ls scripts/hooks/pre-commit
- Pull latest changes from repository

Step 3: Verify Hook Installation

Purpose: Confirm the hook is properly installed and executable

Commands:

# Check hook file exists
ls -l .git/hooks/pre-commit
# Expected: -rwxr-xr-x ... .git/hooks/pre-commit

# View hook contents (first few lines)
head -5 .git/hooks/pre-commit
# Expected: Should show shell script starting with #!/bin/sh

Validation:

File .git/hooks/pre-commit exists
File is executable (permissions include x)
File contains shell script code

If step fails:

Hook file missing: Re-run installation script
Not executable: chmod +x .git/hooks/pre-commit

Step 4: Test Hook

Purpose: Verify the hook runs on commit

Commands:

# Create a test markdown file with linting errors
echo "# Test" > test-lint.md
echo "No blank line before list:" >> test-lint.md
echo "- item 1" >> test-lint.md

# Stage the file
git add test-lint.md

# Try to commit (hook should run and may fail if linting errors)
git commit -m "test: verify pre-commit hook"

# Expected: Hook runs markdown linting
# If there are errors, commit will be blocked

# Clean up test file
git reset HEAD test-lint.md
rm test-lint.md

Validation:

Hook runs when you attempt to commit
You see markdown linting output
Commit is blocked if there are linting errors (expected behavior)

If step fails:

Hook doesn't run: Verify installation in Step 3
Hook runs but always passes: Check hook script contents
Permission errors: Verify hook is executable

Validation

After completing all steps, verify:

Hook Installed:

ls -l .git/hooks/pre-commit
# Expected: File exists and is executable

Hook Runs on Commit:
- Create and stage a markdown file
- Run git commit
- Observe hook output

Can Bypass if Needed:

git commit --no-verify -m "test"
# Expected: Commit succeeds without running hook
git reset HEAD~1  # Undo test commit

Uninstall

If you need to remove the git hooks:

Remove Pre-Commit Hook

# Remove the hook
rm .git/hooks/pre-commit

# Verify removal
ls .git/hooks/pre-commit
# Expected: No such file or directory

When to uninstall:

You prefer to run linting manually
Hook is causing issues
Switching to a different linting workflow

Note: You can always reinstall by running the installation script again.

Troubleshooting

Common Issues

Issue 1: Hook Blocks All Commits

Symptoms:

Every commit attempt is blocked
Linting errors on files you didn't change

Resolution:

# Check what files have linting errors
npm run lint:md

# Fix errors
scripts/lint-markdown.sh --fix

# Or bypass for urgent commits
git commit --no-verify -m "message"

# Then fix linting separately

Issue 2: Hook Doesn't Run

Symptoms:

Commits succeed without any hook output
No linting checks performed

Resolution:

# Verify hook exists and is executable
ls -l .git/hooks/pre-commit

# If missing, reinstall
scripts/install-git-hooks.sh

# If not executable
chmod +x .git/hooks/pre-commit

# Test with verbose output
git commit --dry-run -m "test"

Issue 3: markdownlint-cli2 Not Found

Symptoms:

Hook runs but fails with "command not found"
Error about missing markdownlint-cli2

Resolution:

# Install project dependencies
npm install

# Verify markdownlint-cli2 is available
npx markdownlint-cli2 --version

# If still failing, check hook script
cat .git/hooks/pre-commit

When to Escalate

Escalate if:

Hook installation script fails consistently
Hook causes git to hang or crash
Hook blocks valid commits repeatedly
Need to modify hook behavior

Escalation Contact:

Repository maintainer
Development team lead

Post-Procedure

After installation:

Hook successfully runs on commit attempts
You understand how to bypass with --no-verify
You know how to uninstall if needed
Team members are notified (if setting up for entire team)

Quick Reference

Essential Commands

# Install hooks
scripts/install-git-hooks.sh

# Verify installation
ls -l .git/hooks/pre-commit

# Bypass hook for one commit
git commit --no-verify -m "message"

# Uninstall hook
rm .git/hooks/pre-commit

# Test linting manually
npm run lint:md
scripts/lint-markdown.sh

Notes

Important Notes:

Hook is local to your repository - not committed or shared via git
Each developer must install hooks separately
Hook only runs on git commit, not on git push or other commands
Bypassing with --no-verify should be rare - prefer fixing linting errors

Gotchas:

Hook only lints staged markdown files, not all files
If you have unstaged changes in markdown files, those won't be linted
Journal files in docs/.journal/ are gitignored and won't be linted
Hook runs before commit message editor opens

Related Procedures:

Fix Markdown Linting - for fixing linting errors the hook finds
Contributing Guide - general development workflow

Revision History

Date	Author	Changes
2025-10-20	@tnez	Initial creation