commit-shield 🛡️

Fast, zero-dependency Git commit message and staged file linter.

Enforces Conventional Commits standards and guards against accidental commits of secrets (.env, .pem, id_rsa) or oversized files (> 10MB).

Start here: your first contribution

Featured beginner issue #8: Add regression tests for multiline commit messages. Read CONTRIBUTING.md for setup, claiming an issue, and opening a draft PR.

Repository: commit-guard; PyPI distribution: commit-shield; Python import: commit_guard. Both commit-shield and commit-guard are installed CLI aliases.

Try this from a reviewed source checkout, in the repository root, with Python 3.8+. It uses synthetic inputs and needs no API key or network access:

from commit_guard.checkers import check_commit_message
print(check_commit_message("feat: add example"))

Expected output:

(True, [])

⚡ Why commit-shield?

• Zero dependencies: Written in pure standard Python. Instant install, lightweight, no massive node_modules or heavy binary dependencies.
• Fast: Runs in milliseconds during git commit.
• Pre-commit ready: Seamless drop-in integration with the popular pre-commit framework.
• Dual protection: Validates both commit message formatting AND safeguards against accidentally committed credentials/blobs.

📦 Installation

pip install commit-shield

Or install from source:

git clone https://github.com/lui01212/commit-guard.git
cd commit-guard
pip install -e .

🚀 Usage

1. Check Commit Messages

Validate commit message strings directly:

# Valid commit message -> exit code 0
commit-guard check-msg -m "feat(auth): add google oauth2 login provider"

# Invalid commit message -> exit code 1 with actionable errors
commit-guard check-msg -m "fixed stuff"

Output:

[commit-guard] Commit message validation failed:
  - Header does not follow Conventional Commits format: '<type>(<scope>): <description>'.
    Received: 'fixed stuff'
    Allowed types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test

2. Check Staged Files (Secrets & Large Blobs)

# Checks all currently staged files in git
commit-guard check-files --strict

3. One-Click Git Hook Setup (No pre-commit framework needed)

Install the hook directly into your local .git/hooks/commit-msg:

commit-guard install

🔧 Integration with pre-commit

Add this to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/lui01212/commit-guard
    rev: v0.2.0
    hooks:
      - id: commit-guard-msg
      - id: commit-guard-files

⚙️ Configuration

commit-guard works zero-config out of the box, but can be fully customized via .commit-guard.toml or [tool.commit-guard] in pyproject.toml:

# .commit-guard.toml
max_header_len = 72
require_scope = false
skip_merge_commits = true
max_size_mb = 10.0

# Add extra sensitive patterns to protect
extra_sensitive_patterns = ["*.secret", "*_token.json"]

# Allowlist false-positives
allowlist = ["*.example", "*.sample", "*.template"]

See .commit-guard.toml.example for all available options.

📋 Allowed Commit Types

🤝 Contributing

Contributions are warmly welcomed! We have plenty of beginner-friendly tasks:

• Adding custom pattern checks.
• Expanding sensitive file extension detections.
• Adding localized error messages (Vietnamese, Spanish, etc.).

Please see CONTRIBUTING.md for details on how to get started.

📄 License

MIT License © 2026 lui01212