4.8 KiB

Raw Blame History

TimeSafari Debug Hook Guide

Complete Guide for Team Members

Date: 2025-01-27
Author: Matthew Raymer
Status: ✅ ACTIVE - Ready for production use

🎯 Overview

A pre-commit hook that automatically detects and prevents debug code from reaching protected branches (master, main, production, release, stable). This ensures production code remains clean while allowing free development on feature branches.

🚀 Quick Installation

From within the TimeSafari repository:

./scripts/install-debug-hook.sh

This automatically installs, updates, and verifies the hook in your current repository.

🔧 Manual Installation

Copy files manually:

cp .git/hooks/pre-commit /path/to/your/repo/.git/hooks/
cp .git/hooks/debug-checker.config /path/to/your/repo/.git/hooks/
chmod +x /path/to/your/repo/.git/hooks/pre-commit

📋 What Gets Installed

pre-commit - Main hook script (executable)
debug-checker.config - Configuration file
README.md - Documentation and troubleshooting

🎯 How It Works

Branch Detection: Only runs on protected branches
File Filtering: Automatically skips tests, scripts, and documentation
Pattern Matching: Detects debug code using regex patterns
Commit Prevention: Blocks commits containing debug code

🌿 Branch Behavior

Protected branches (master, main, production, release, stable): Hook runs automatically
Feature branches: Hook is skipped, allowing free development with debug code

🔍 Debug Patterns Detected

Console statements: console.log, console.debug, console.error
Template debug: Debug:, debug: in Vue templates
Debug constants: DEBUG_, debug_ variables
HTML debug: <!-- debug comments
Debug attributes: debug="true" attributes
Vue debug: v-if="debug", v-show="debug"
Debug TODOs: TODO debug, FIXME debug

📁 Files Automatically Skipped

Test files: *.test.js, *.spec.ts, *.test.vue
Scripts: scripts/ directory
Test directories: test-* directories
Documentation: docs/, *.md, *.txt
Config files: *.json, *.yml, *.yaml
IDE files: .cursor/ directory

✅ Verification

After installation, verify it's working:

# Check if files exist
ls -la .git/hooks/pre-commit
ls -la .git/hooks/debug-checker.config

# Test the hook manually
.git/hooks/pre-commit

# Test with actual commit
echo "console.log('test')" > test.vue
git add test.vue
git commit -m "test"  # Should be blocked

📊 Example Output

❌ Debug code detected in staged files!
   Branch: master
   Files checked: 1
   Errors found: 3

   🚨 AccountViewView.vue: Found debug pattern 'console\.'
   🚨 AccountViewView.vue: Found debug pattern 'Debug:'
   🚨 AccountViewView.vue: Found debug pattern 'DEBUG_'

💡 Please remove debug code before committing to master

⚙️ Configuration

Edit .git/hooks/debug-checker.config to customize:

Protected branches: Add/remove branches as needed
Debug patterns: Customize what gets detected
Skip patterns: Adjust file filtering rules

🚨 Emergency Bypass

If you absolutely need to commit debug code to a protected branch:

git commit --no-verify -m "emergency: debug code needed"

⚠️ Warning: This bypasses all pre-commit hooks. Use sparingly.

🔄 Updates

When the hook is updated in the main repository:

./scripts/install-debug-hook.sh

🚨 Troubleshooting

Issue	Solution
Hook not running	Check if on protected branch, verify permissions
Permission denied	Run `chmod +x .git/hooks/pre-commit`
Files not found	Ensure you're copying from TimeSafari repo
False positives	Edit `debug-checker.config` to customize patterns

🧪 Testing

A test script is available at scripts/test-debug-hook.sh to verify the hook works correctly.

💡 Best Practices

Use feature branches for development with debug code
Use proper logging instead of console statements (logger.info, logger.debug)
Test thoroughly before merging to protected branches
Review commits to ensure no debug code slips through
Keep hooks updated across all repositories

📚 Additional Resources

Hook documentation: .git/hooks/README.md
Configuration: .git/hooks/debug-checker.config
Test script: scripts/test-debug-hook.sh
Installation script: scripts/install-debug-hook.sh

🎯 Team Workflow

Recommended setup:

Repository setup: Include hook files in .githooks/ directory
Team onboarding: Run installation script in each repo
Updates: Re-run installation script when hooks are updated
Documentation: Keep this guide updated

Status: Active and enforced
Last Updated: 2025-01-27
Maintainer: Matthew Raymer

4.8 KiB Raw Blame History