forked from trent_larson/crowd-funder-for-time-pwa
2d17bfd3b4
- Update BUILDING.md with current build system information - Modernize various README files across the project - Update CHANGELOG.md with recent changes - Improve documentation consistency and formatting - Update platform-specific documentation (iOS, Electron, Docker) - Enhance test documentation and build guides
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: `docs/`, `*.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"
|
|
```
|
|
|
|
⚠️ **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
|