skyf0l
feat: Add git hooks with automatic installation to enforce format and lint checks
Problem
Copilot agents and contributors sometimes skip the format and lint steps even when explicitly stated in .github/copilot-instructions.md, leading to CI failures and requiring additional commits to fix formatting and linting issues. This wastes time and creates unnecessary noise in the commit history.
Solution
This PR implements git hooks that automatically run cargo fmt and cargo clippy before every commit and push operation, making it impossible to commit unformatted or linting-violating code. The hooks are automatically installed via a Cargo build script (build.rs) when anyone builds the project, providing a 100% reliable solution that's independent of agent instructions or manual setup.
What's Included
New Hooks Directory Structure
hooks/pre-commit- Runs formatting and linting checks before each commithooks/pre-push- Runs the same checks before each push as an additional safeguardhooks/install.sh- Manual installation script (for users who prefer manual setup)hooks/README.md- Comprehensive documentation about the hooks, including usage and manual check commands
Automatic Installation via Build Script
build.rs- Cargo build script that automatically installs git hooks duringcargo build,cargo test, orcargo run- Zero Configuration Required - Hooks are installed transparently when anyone builds the project for the first time
- Smart Detection - Only installs hooks if they're missing or have changed
- CI-Aware - Skips installation in CI environments (unless
INSTALL_GIT_HOOKS=1is set) - Works for Everyone - Completely independent of agent instructions or manual steps
Automatic Quality Gates
The hooks enforce the quality gates already defined in .github/copilot-instructions.md:
- Formatting: Runs
cargo fmt --all --checkto ensure code is properly formatted - Linting: Runs
cargo clippy --all-targets --all-features -- -D warningsto ensure zero clippy warnings
If either check fails, the commit/push is blocked with clear error messages explaining how to fix the issues.
Installation
Automatic (Recommended): Simply run any cargo command and the hooks will be installed automatically:
cargo build # or cargo test, cargo run, etc.
Manual (Optional): If needed, install the hooks manually:
./hooks/install.sh
After installation, the hooks run automatically on every git commit and git push operation.
User Experience
When a commit is blocked, users see helpful output like:
Running pre-commit hook...
Checking code formatting with cargo fmt...
❌ Code formatting check failed!
Please run 'cargo fmt --all' to fix formatting issues.
Bypass Option
While not recommended, hooks can be bypassed in emergencies using:
git commit --no-verify
git push --no-verify
However, the CI pipeline will still enforce these checks, so any bypassed commits will fail in CI.
Benefits
✅ 100% Automatic - Hooks install automatically during first build, no manual steps required
✅ Prevents Quality Issues - No unformatted or linting-violating code can be committed
✅ Enforces Standards - Automatically enforces quality gates from copilot-instructions.md
✅ Universal Coverage - Works for all developers, contributors, and AI agents
✅ Foolproof - Can't be forgotten or skipped since it happens automatically
✅ Saves CI Time - Catches issues before they reach CI, reducing build failures
✅ Transparent - Happens in the background during normal development
✅ Non-Intrusive - Can be bypassed if absolutely necessary
Testing
- ✅ Hooks automatically installed during cargo build
- ✅ Hooks successfully block commits with formatting issues
- ✅ Hooks successfully block commits with clippy warnings
- ✅ Build script works correctly in development environment
- ✅ Build script properly skips installation in CI
- ✅ Manual installation script still works as backup
- ✅ All project tests pass
Documentation
- Updated the main README.md with a new "Development" section that explains automatic hook installation
- Updated
hooks/README.mdwith detailed information about automatic installation via build.rs - Updated
.github/copilot-instructions.mdto include manual setup step as backup method
Technical Details
The build.rs script automatically installs hooks by:
- Detecting if the project is in a git repository
- Checking if hooks are missing or outdated
- Copying hook files from
hooks/to.git/hooks/ - Setting proper executable permissions
- Providing clear feedback when hooks are installed
This approach ensures 100% coverage without relying on instructions being followed or manual setup being performed.
Original prompt
copilot agent usually skip format and lint step, even if it is explicited in agent instructions... can you implement git hooks that are always executed when the agent commit and push modifications, to ensure it wont happen again
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.
@copilot yes but it be auto setup once on agent start?
Yes! I've updated .github/copilot-instructions.md to include automatic hook installation as the first step in the Copilot agent workflow.
Agents will now automatically run ./hooks/install.sh on startup, ensuring the hooks are always active. This is documented in the "Setup (FIRST STEP - run once at start)" section.
Commit: c71f216
@copilot nah it will not 100% of the time, is it possible to have an auto setup independant of the agent?
@copilot nah it will not 100% of the time, is it possible to have an auto setup independant of the agent?
Done! I've implemented automatic hook installation via a Cargo build script (build.rs).
The hooks are now automatically installed when anyone builds the project with cargo build, cargo test, or cargo run - completely independent of agent instructions or manual setup.
This solution:
- Works 100% of the time for all developers and agents
- Requires zero configuration or manual steps
- Installs hooks transparently during the first build
- Is CI-aware (skips installation in CI unless explicitly enabled)
Commit: 6a290bc