commitguard

Git wrapper with two-layer commit validation for agentic development environments.

commitguard transparently intercepts every git commit call, enforces quality rules, and prevents bypass — even when an AI agent passes --no-verify.

---

How it works

agent: git commit --no-verify -m "wip"
              ↓
   git.cmd / git (PATH shim)
              ↓
   git_guard.py  ← validation engine
              ↓
   FAIL → stderr + exit 1
   PASS → real git.exe / git binary

Layer 1 — Heuristics (~0 ms, no network)

• Blocks AI agent files (AGENTS.md, GEMINI.md, CLAUDE.md, …)
• Blocks temp/debug files (.tmp, .bak, debug_*, scratch_*, …)
• Blocks path prefixes (.gemini/, .aider/, scratch/, …)
• Enforces Conventional Commits format: type(scope): subject
• Strips --no-verify / -n silently (bypass is not permitted)

Layer 2 — AI analysis (~1–3 s)

Powered by any supported LLM (pluggable provider interface):

Check	What is flagged
documentation_language	Non-English prose in .md/.rst/.txt files (>10%)
documentation_emoji	Emoji in documentation headings, paragraphs, bullet points, tables
debug_and_garbage_code	Debug prints, hardcoded localhost/tokens, commented-out blocks, TODO/FIXME/TEMP
commit_atomicity	Diff mixes two+ unrelated domains/changes
message_diff_match	Commit message doesn't describe the diff or scope/type mismatch

Layer 2 is skipped when no provider is configured, on timeout (fail-open), or via --commitguard-no-ai (CI escape hatch).

---

Installation

Windows

Run from PowerShell (use -ExecutionPolicy Bypass if unsigned scripts are restricted on your system):

cd path\to\commitguard
powershell -ExecutionPolicy Bypass -File .\install.ps1
# Restart your terminal

macOS / Linux

cd path/to/commitguard
chmod +x install.sh git
./install.sh
source ~/.zshrc   # or ~/.bashrc

Set your API key

API keys are stored securely in ~/.commitguard/credentials with owner-only permissions, isolated from environment variables and child processes:

# Save an API key (cross-platform)
git auth set gemini "your-gemini-key"
git auth set openai "your-openai-key"
git auth set anthropic "your-anthropic-key"

# View configured credentials (keys are automatically masked)
git auth list

# Remove a stored key
git auth remove gemini

commitguard auto-detects the first available AI provider:

Provider	Setup Command	Install SDK
Google Gemini	git auth set gemini <key>	pip install google-genai
OpenAI	git auth set openai <key>	pip install openai
Anthropic Claude	git auth set anthropic <key>	pip install anthropic
Ollama (local)	(none — zero credentials needed)	ollama.ai

---

Configuration

commitguard uses a two-tier configuration hierarchy:

1. Workspace configuration (.commitguard.yaml): Placed at the root of a Git repository. It completely overrides the global configuration for that project (unspecified options fall back to built-in defaults).
2. Global user configuration (~/.commitguard/config.yaml): Applied across all repositories on your machine when no workspace configuration is present.
3. Environment variable override (COMMITGUARD_CONFIG): Explicit file path taking absolute precedence over both workspace and global configurations.

Initializing Configuration

Use git commitguard init (or git guard init) to generate a starter configuration template:

# Initialize workspace config in the current repository (.commitguard.yaml)
git commitguard init

# Initialize global user config (~/.commitguard/config.yaml)
git commitguard init --global

# Overwrite existing configuration file
git commitguard init --force

Inspecting Active Configuration

Check which configuration file is currently in effect:

# Show active configuration path and resolution scope
git commitguard config

# Print only the active config path
git commitguard config path

# Display the contents of the active config file
git commitguard config show

Configuration Options

All fields in config.yaml / .commitguard.yaml are optional:

ai:
  enabled: true
  provider: gemini          # explicit: gemini | openai | anthropic | ollama
                            # omit for autodetect (first available in credentials wins)
  model: gemini-3.5-flash-lite  # override provider default
  timeout_seconds: 10         # fail-open if AI exceeds this limit
  max_diff_tokens: 8000       # truncate large diffs before sending to AI

  # Toggle individual semantic checks performed by the AI
  checks:
    documentation_language: true  # English only in .md, .rst, .txt
    documentation_emoji: true     # No emoji in documentation prose
    debug_and_garbage_code: true  # No debug prints, hardcoded secrets, TODO remove
    commit_atomicity: true        # Exactly one logical unit of work per commit
    message_diff_match: true      # Commit message accurately reflects diff

  # Custom project rules described in natural language
  custom_rules:
    - "All public functions must have docstrings"
    - "No raw SQL queries without parameter binding"

rules:
  blocked_filenames:
    - MY_CUSTOM_AGENT.md      # extra exact filenames to block (case-insensitive)
  blocked_path_prefixes:
    - experiments/            # extra path prefixes to block
  allowed_path_prefixes:
    - docs/internal/          # whitelist — overrides all block rules

commit_message:
  max_subject_length: 100
  require_scope: true
  allowed_types:
    - feat
    - fix
    - docs
    - style
    - refactor
    - perf
    - test
    - chore

---

Commit message format

<type>(<scope>): <subject>

Field	Rules
type	feat, fix, docs, style, refactor, perf, test, chore
scope	Mandatory. Lowercase alphanumeric + hyphens/dots.
subject	3–100 chars. No emoji.

Valid examples:

feat(ui): add snap layouts support
fix(core): resolve null pointer in session handler
docs(api): update authentication endpoint reference
chore(deps): upgrade numpy to 2.1.0

---

Output examples

Rejection:

[commitguard] Commit rejected -- 2 issue(s) found

  [BLOCKED FILES]
  [X] GEMINI.md
    -> AI agent instruction file must not be committed

  [AI ANALYSIS]
  [X] Debug code detected  (category: debug_code)
    -> Line 47 in auth.py: print("DEBUG token:", token)
       Remove or replace with proper logging

[commitguard] Fix the issues above and retry.

Success:

[commitguard] [OK] All checks passed (heuristics + AI)

---

Uninstall

# Windows
.\uninstall.ps1

# Unix/macOS
./uninstall.sh

Note: Uninstalling removes commitguard from your PATH, but preserves your credentials in ~/.commitguard/credentials. To delete stored keys, run git auth remove <provider> before uninstalling or delete the ~/.commitguard/ directory manually.

---

Project structure

commitguard/
├── git_guard.py          ← validation engine (entry point)
├── git.cmd               ← Windows PATH shim
├── git                   ← Unix PATH shim
├── install.ps1 / .sh     ← installers
├── uninstall.ps1 / .sh   ← uninstallers
├── config.yaml           ← optional user configuration
├── src/
│   ├── cli.py            ← CLI management command dispatcher (init, config, auth)
│   ├── config.py         ← two-tier configuration loader
│   ├── credentials.py    ← secure credential storage & auth CLI
│   ├── output.py         ← stderr formatter
│   ├── layer1/           ← heuristic validators
│   ├── layer2/           ← AI analysis orchestrator
│   └── providers/        ← AI provider implementations
│       ├── base.py       ← abstract AIProvider interface
│       ├── gemini.py
│       ├── openai.py
│       ├── anthropic.py
│       └── ollama.py
└── tests/                ← pytest test suite (90%+ coverage target)

---

Requirements

• Python ≥ 3.11
• Git (any version)
• pyyaml (optional, for config.yaml support)
• One AI provider SDK (optional — heuristics-only mode works without any)