Skip to main content

git-hooks

Git hooks management and installation - Automates installation of pre-commit, pre-push, and git safety hooks.

📖 Complete Git Hooks Guide - Detailed documentation with troubleshooting and bypass methods.

Quick Overview​

Supernal Coding provides three main git hooks:

  • Pre-commit: Type duplication checking + branch protection
  • Pre-push: Full test suite validation + build checks
  • Git Safety: Main/master branch protection

Usage​

# Install all git hooks (recommended)
sc git-hooks install

# Install specific hooks
sc git-hooks install pre-commit
sc git-hooks install pre-push
sc git-hooks install all

# Check installation status
sc git-hooks status

# Remove hooks
sc git-hooks remove

Examples​

Basic Installation​

# Install all hooks in current repository
sc git-hooks install

# Output:
# 🔧 Installing Supernal Coding git safety hooks...
# ✅ Pre-commit hook installed (type checking, branch protection)
# ✅ Pre-push hook installed (test validation, build checks)
# ✅ Git safety hooks installed (main branch protection)

Status Check​

sc git-hooks status

# Output:
# 📋 Git Hooks Status:
# ✅ Pre-commit hook: Installed and executable
# ✅ Pre-push hook: Installed and executable  
# ✅ Git safety: Main branch protection active
# 🔍 Type checking: Enabled (scripts/check-type-duplicates.cjs)

Emergency Bypass​

# Bypass pre-commit hook (emergency only)
git commit --no-verify -m "Emergency hotfix"

# Bypass pre-push hook (use with caution)
git push --no-verify

# Alternative pre-push bypass
SC_SKIP_PRE_PUSH=true git push

Hook Details​

Pre-commit Hook​

  • ✅ Type Duplication Checking: Scans for duplicate types/interfaces
  • 🔒 Branch Protection: Prevents direct commits to main/master
  • 📝 CLI Sync: Updates agent rules with latest commands
  • ⚠️ Branch Naming: Validates naming conventions

Pre-push Hook​

  • 🧪 Test Validation: Runs full test suite (285+ tests)
  • 🏗️ Build Validation: Checks if build script succeeds
  • 🔍 Final Type Check: Last scan for duplications (warning only)
  • 📊 Progress Display: Shows branch and validation status

Git Safety Hook​

  • 🚫 Main Branch Protection: Absolute prevention of direct commits
  • 📚 Educational Messaging: Guides users to proper workflow
  • 🆘 Emergency Instructions: Shows bypass methods when needed

Configuration​

Git hooks behavior is configured via supernal-code.config.toml:

[type_duplication]
enabled = true
pre_commit_hook = true
block_commits_on_duplications = true
allow_force_commits = true

[git_workflow]
protect_main_branches = ["main", "master"]
require_branch_naming = false
auto_sync_cli_docs = true

Troubleshooting​

Common Issues​

  • Hook not executable: chmod +x .git/hooks/*
  • Test failures: Debug with npm test
  • Type checker errors: Check node scripts/check-type-duplicates.cjs
  • Permission denied: Verify repository ownership

Emergency Procedures​

  1. Document the reason for any bypass
  2. Fix underlying issue immediately
  3. Re-run validations manually
  4. Inform team about bypass usage

Category​

Git & Workflow

📖 Complete Documentation | 🐛 Troubleshooting | 🚀 Workflow Guide

This documentation reflects the actual implementation of Supernal Coding's git hooks.