git-approve: A Human-AI Collaborative Code Review Mechanism for AI-Assisted Development

Introduction to the git-approve Project

Original Author/Maintainer: tbrugere Source Platform: GitHub Original Link: https://github.com/tbrugere/git-approve

git-approve is a tool that provides a file-level approval mechanism for git, designed to address the lack of manual review in AI-assisted development. It enforces manual review of AI-generated code changes via pre-commit hooks, balancing automation and human oversight. Its core design is based on a blob OID approval mechanism, ensuring that unreviewed code cannot be committed and providing security for AI collaboration workflows.

New Challenges in AI-Assisted Development

With the popularity of AI coding assistants like GitHub Copilot and Claude Code, the development process has changed from "Developer writes → Stages → Reviews → Commits" to "AI generates → Developer stages → Reviews → Commits". However, the staging action can no longer serve as an approval signal (since the code is not written by the developer), and Git natively lacks a file-level approval marker—this is exactly the problem git-approve aims to solve.

Core Design and Command Flow

git-approve's core is the approved ledger under the .git directory, which records file paths and the blob OID of staged content:

• Blob OID as Key: If content changes, the OID changes, and previous approvals automatically become invalid, requiring re-review.
• Worktree Isolation: The ledger is stored per worktree and does not leak across branches/features.

Provided commands include:

• git-approve approve [PATHS] (alias gok): Approve specified/all staged files.
• git-approve revoke [PATHS] (alias gnok): Revoke approval.
• git-approve status (alias gcs): Show approval status.
• enable/disable: Enable/disable the approval mechanism for the current worktree.

Integration and Tool Support

1. Pre-commit Hook: Checks if the ledger exists → verifies if the OID of files to be committed is approved → blocks unapproved commits. Supports partial commits, checking only the files to be committed.
2. Hook Coexistence: Provides a _chain script to resolve conflicts between global hooksPath and local hooks (e.g., husky).
3. Neovim Plugin: Provides commands like GApproveReview (view diff of unapproved staged files), GApprove (approve current file), GUnapprove (revoke approval) for easy in-editor operations.

Security Boundaries and Known Limitations

• Bypass Mechanism: git commit --no-verify can skip checks (emergency escape hatch; prohibited for AI use).
• GUI Compatibility: Some GUI clients do not include git-approve in their PATH, leading to hook execution failures.
• Special Filenames: Filenames containing tabs/newlines are not supported (the ledger uses tabs as separators).
• Local hooksPath Shadowing: The repository's local core.hooksPath (e.g., husky v9) overrides global settings; team-wide configuration is required.

Practical Significance and Deployment Recommendations

Practical Significance: Clarifies human-AI boundaries (AI generates, humans are responsible for review), suitable for regulated industries (finance/healthcare), safety-critical systems, and teams requiring audit trails.

Deployment Steps:

1. Install git-approve via uv tool install or pipx install.
2. Set the global core.hooksPath to point to git-approve's hooks directory.
3. Configure shell aliases (gok/gnok/gcs).
4. Optionally install the Neovim plugin.
5. Verify no bypassed approval commits in CI/CD.

Conclusion

git-approve is a small but refined tool that solves real review problems in AI-assisted development. It does not limit AI capabilities; instead, it ensures humans remain in the decision loop, maintaining final control over code quality and system security, and serving as infrastructure for responsible AI adoption.