Post-Checkout Hook

Automatic environment synchronization after branch checkout, ensuring dependencies and configuration are always current.

Purpose

The post-checkout hook runs automatically after git checkout or git switch to:

Sync Dependencies - Install/update dependencies when lock files change
Update Submodules - Ensure submodules are initialized and updated
Environment Setup - Validate and refresh environment configuration
Database Migrations - Prompt for pending migrations
Cache Invalidation - Clear stale caches after branch switch

Priority: P0 - Critical for developer experience Impact: Eliminates "works on my machine" issues from stale dependencies

Trigger

Event: post-checkout (git hook) Blocking: No - Informational only, does not block checkout Timeout: 60 seconds Arguments: $1=previous_ref, $2=new_ref, $3=flag (1=branch checkout)

Checks Performed

Dependency Management (P0)

Python (pip/poetry) - Detect changes to requirements.txt, Pipfile.lock, poetry.lock
Node.js (npm/yarn/pnpm) - Detect changes to package-lock.json, yarn.lock
Rust (cargo) - Detect changes to Cargo.lock
Go - Detect changes to go.sum
Auto-Install - Optionally auto-install when lock files change

Submodule Sync (P0)

Initialize - Initialize any new submodules
Update - Update submodules to correct commit
Detached HEAD - Warn about detached HEAD states
Missing - Alert on missing submodule directories

Environment Validation (P1)

Environment Files - Check .env exists and has required variables
Config Files - Validate configuration files present
Tool Versions - Verify required tool versions (node, python, etc.)
Docker Services - Check if docker-compose services need restart

Database Checks (P2)

Migration Status - Detect pending database migrations
Schema Changes - Alert on schema file changes
Seed Data - Prompt for seed data updates

Cache Management (P2)

Build Cache - Clear stale build artifacts
Test Cache - Clear pytest/jest cache on significant changes
Module Cache - Clear pycache, node_modules/.cache

Installation

Method 1: Pre-commit Framework

# Add to .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: coditect-post-checkout
        name: CODITECT Post-checkout
        entry: bash .coditect/hooks/post-checkout
        language: system
        always_run: true
        stages: [post-checkout]

# Install post-checkout hook
pre-commit install --hook-type post-checkout

Method 2: Direct Git Hook

# Copy hook script
cp .coditect/hooks/post-checkout .git/hooks/post-checkout
chmod +x .git/hooks/post-checkout

Method 3: Manual Script

# Run manually after checkout
bash .coditect/hooks/post-checkout HEAD HEAD~1 1

Configuration

Environment Variables

Variable	Default	Description
`CODITECT_AUTO_INSTALL`	`prompt`	auto/prompt/never for dependency install
`CODITECT_AUTO_SUBMODULE`	`true`	Auto-update submodules
`CODITECT_SKIP_ENV_CHECK`	`false`	Skip environment validation
`CODITECT_CLEAR_CACHE`	`false`	Clear caches on checkout
`CODITECT_QUIET`	`false`	Suppress informational output

.coditect/hooks.yaml

post-checkout:
  enabled: true
  timeout: 60
  dependencies:
    auto_install: prompt  # auto, prompt, never
    managers:
      - pip
      - npm
      - cargo
  submodules:
    auto_update: true
    warn_detached: true
  environment:
    check_dotenv: true
    required_vars:
      - DATABASE_URL
      - API_KEY
  cache:
    clear_on_checkout: false
    directories:
      - __pycache__
      - .pytest_cache
      - node_modules/.cache

Bypass

Post-checkout hooks are non-blocking and informational. To suppress:

# Quiet mode
CODITECT_QUIET=true git checkout feature/branch

# Skip environment checks
CODITECT_SKIP_ENV_CHECK=true git checkout feature/branch

# Skip all post-checkout
GIT_SKIP_POST_CHECKOUT=1 git checkout feature/branch

Examples

Standard Checkout Output

$ git checkout feature/new-api

Switched to branch 'feature/new-api'

CODITECT Post-checkout v1.0.0
================================

[1/4] Checking Dependencies...
  📦 package-lock.json changed (5 files different)

  Dependencies may be out of date. Install now?
  [Y]es / [N]o / [A]lways / [S]kip: Y

  Running: npm ci
  ✅ Dependencies installed (12.3s)

[2/4] Updating Submodules...
  ✅ All submodules up to date (2 submodules)

[3/4] Checking Environment...
  ✅ .env file present
  ✅ All required variables set
  ⚠️  DATABASE_URL points to dev database

[4/4] Additional Checks...
  ℹ️  2 pending database migrations
      Run: python manage.py migrate

================================
✅ Post-checkout complete
================================

Lock File Changes Detected

$ git checkout main

Switched to branch 'main'

CODITECT Post-checkout v1.0.0
================================

[1/4] Checking Dependencies...
  📦 Changes detected in lock files:

  Modified:
    - requirements.txt (+3 packages)
    - package-lock.json (15 packages updated)

  ⚠️  Your dependencies may be out of sync!

  Run to sync:
    pip install -r requirements.txt
    npm ci

[2/4] Updating Submodules...
  ✅ All submodules up to date

================================

Submodule Issues

$ git checkout develop

Switched to branch 'develop'

CODITECT Post-checkout v1.0.0
================================

[2/4] Updating Submodules...
  ⚠️  Submodule issues detected:

  submodules/core/coditect-core:
    Status: Detached HEAD
    Expected: abc1234
    Current:  def5678

  To fix:
    git submodule update --init --recursive

  Or checkout specific commit:
    cd submodules/core/coditect-core
    git checkout abc1234

================================

Missing Environment

$ git checkout feature/api-v2

Switched to branch 'feature/api-v2'

CODITECT Post-checkout v1.0.0
================================

[3/4] Checking Environment...
  ❌ Environment issues detected:

  Missing .env file!

  Create from template:
    cp .env.example .env

  Missing required variables:
    - API_SECRET (required for authentication)
    - REDIS_URL (required for caching)

  See .env.example for all required variables.

================================

Troubleshooting

Hook Not Running

Symptom: No output after checkout Solution:

# Verify hook is installed
ls -la .git/hooks/post-checkout

# Check hook is executable
chmod +x .git/hooks/post-checkout

# Run manually to test
bash .git/hooks/post-checkout HEAD HEAD~1 1

Slow Dependency Install

Symptom: Hook takes too long Solution:

# Use quiet mode
CODITECT_QUIET=true git checkout branch

# Disable auto-install
CODITECT_AUTO_INSTALL=never git checkout branch

# Configure in hooks.yaml
# post-checkout:
#   dependencies:
#     auto_install: never

Submodule Update Fails

Symptom: "Unable to checkout submodule" Solution:

# Force submodule update
git submodule update --init --recursive --force

# Reset submodule
git submodule deinit -f submodules/problematic
git submodule update --init submodules/problematic

# Check for uncommitted changes in submodule
cd submodules/problematic
git status
git stash  # if needed

Environment Variables Not Set

Symptom: "Missing required variables" Solution:

# Check .env exists
ls -la .env

# Copy from example
cp .env.example .env

# Edit to add required values
$EDITOR .env

# Verify variables
grep -E "^(DATABASE_URL|API_KEY)=" .env

Performance

Check	Typical Time	Max Time
Dependency Check	200ms	1s
Auto-Install (npm ci)	10-30s	60s
Submodule Update	500ms-5s	30s
Environment Check	100ms	500ms
Cache Clear	200ms	2s
Total (no install)	1-2s	5s
Total (with install)	15-40s	60s

Optimization Tips:

Use npm ci instead of npm install (faster, more reliable)
Use pnpm for faster Node.js dependency management
Configure auto_install: never for faster checkouts
Use shallow submodule clones for large repos

pre-commit-hook - Code quality before commit
pre-push-hook - Test verification before push
ci-integration-hook - GitHub Actions integration

Implementation Script

The implementation script should be created at:

.coditect/hooks/post-checkout (main script - to be created)

Changelog

v1.0.0 - December 8, 2025

Initial comprehensive documentation
Defined dependency sync behavior
Added submodule update checks
Created environment validation
Added cache management options

Purpose​

Trigger​

Checks Performed​

Dependency Management (P0)​

Submodule Sync (P0)​

Environment Validation (P1)​

Database Checks (P2)​

Cache Management (P2)​

Installation​

Method 1: Pre-commit Framework​

Method 2: Direct Git Hook​

Method 3: Manual Script​

Configuration​

Environment Variables​

.coditect/hooks.yaml​

Bypass​

Examples​

Standard Checkout Output​

Lock File Changes Detected​

Submodule Issues​

Missing Environment​

Troubleshooting​

Hook Not Running​

Slow Dependency Install​

Submodule Update Fails​

Environment Variables Not Set​

Performance​

Related Hooks​

Implementation Script​

Changelog​

v1.0.0 - December 8, 2025​