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

Inside a git repository the staged content is always scanned for secrets. When file paths are given (as the pre-commit framework does), the scan covers the staged changes of those files only.

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

Install a commit-msg hook (message format) and a pre-commit hook (check-files --strict) into the repository's hooks directory:

commit-guard install

# Only the commit-msg hook
commit-guard install --msg-only

If core.hooksPath is set (husky, lefthook and similar tools), install refuses rather than writing hooks git would never run. Call commit-guard check-msg "$1" and commit-guard check-files --strict from that tool's hooks instead.

🔧 Integration with pre-commit

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

repos:
  - repo: https://github.com/lui01212/commit-guard
    rev: v0.4.1
    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 file patterns. These are regular expressions matched
# against the path; single quotes keep the backslashes literal.
extra_sensitive_patterns = ['\.secret$', '_token\.json$']

# Allowlist false-positives (shell-style globs)
allowlist = ["*.example", "*.sample", "*.template"]

Configuration is looked up from the current directory upward to the repository root. Git runs hooks from the repository root, so put the file there; a file in a subdirectory only applies when you run commit-guard by hand from inside it.

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