125 lines
3.4 KiB
Markdown
125 lines
3.4 KiB
Markdown
# TimeSafari Git Hooks
|
||
|
||
This directory contains custom Git hooks for the TimeSafari project.
|
||
|
||
## Debug Code Checker Hook
|
||
|
||
### Overview
|
||
|
||
The `pre-commit` hook automatically checks for debug code when committing to protected branches (master, main, production, release). This prevents debug statements from accidentally reaching production code.
|
||
|
||
### How It Works
|
||
|
||
1. **Branch Detection**: Only runs on protected branches (configurable)
|
||
2. **File Filtering**: Automatically skips test files, scripts, and documentation
|
||
3. **Pattern Matching**: Detects common debug patterns using regex
|
||
4. **Commit Prevention**: Blocks commits containing debug code
|
||
|
||
### Protected Branches (Default)
|
||
|
||
- `master`
|
||
- `main`
|
||
- `production`
|
||
- `release`
|
||
- `stable`
|
||
|
||
### 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: `doc/`, `*.md`, `*.txt`
|
||
- Config files: `*.json`, `*.yml`, `*.yaml`
|
||
- IDE files: `.cursor/` directory
|
||
|
||
### Configuration
|
||
|
||
Edit `.git/hooks/debug-checker.config` to customize:
|
||
|
||
- Protected branches
|
||
- Debug patterns
|
||
- Skip patterns
|
||
- Logging level
|
||
|
||
### Testing the Hook
|
||
|
||
Run the test script to verify the hook works:
|
||
|
||
```bash
|
||
./scripts/test-debug-hook.sh
|
||
```
|
||
|
||
### Manual Testing
|
||
|
||
1. Make changes to a file with debug code
|
||
2. Stage the file: `git add <filename>`
|
||
3. Try to commit: `git commit -m 'test'`
|
||
4. Hook should prevent commit if debug code is found
|
||
|
||
### Bypassing the Hook (Emergency)
|
||
|
||
If you absolutely need to commit debug code to a protected branch:
|
||
|
||
```bash
|
||
git commit --no-verify -m "emergency: debug code needed"
|
||
```
|
||
|
||
âš ï¸<EFBFBD> **Warning**: This bypasses all pre-commit hooks. Use sparingly and only in emergencies.
|
||
|
||
### Troubleshooting
|
||
|
||
#### Hook not running
|
||
|
||
- Ensure the hook is executable: `chmod +x .git/hooks/pre-commit`
|
||
- Check if you're on a protected branch
|
||
- Verify the hook file exists and has correct permissions
|
||
|
||
#### False positives
|
||
|
||
- Add legitimate debug patterns to skip patterns in config
|
||
- Use proper logging levels (`logger.info`, `logger.debug`) instead of console
|
||
- Move debug code to feature branches first
|
||
|
||
#### Hook too strict
|
||
|
||
- Modify debug patterns in config file
|
||
- Add more file types to skip patterns
|
||
- Adjust protected branch list
|
||
|
||
### Best Practices
|
||
|
||
1. **Use feature branches** for development with debug code
|
||
2. **Use proper logging** instead of console statements
|
||
3. **Test thoroughly** before merging to protected branches
|
||
4. **Review commits** to ensure no debug code slips through
|
||
5. **Keep config updated** as project needs change
|
||
|
||
### Integration with CI/CD
|
||
|
||
This hook works locally. For CI/CD pipelines, consider:
|
||
|
||
- Running the same checks in your build process
|
||
- Adding ESLint rules for console statements
|
||
- Using TypeScript strict mode
|
||
- Adding debug code detection to PR checks
|
||
|
||
### Support
|
||
|
||
If you encounter issues:
|
||
|
||
1. Check the hook output for specific error messages
|
||
2. Verify your branch is in the protected list
|
||
3. Review the configuration file
|
||
4. Test with the provided test script
|
||
5. Check file permissions and git setup
|