Git Commit Analyzer

中文 · Français · Español

• Official website: https://zhanghe.dev/products/git-commit-analyzer
• Releases: https://github.com/zh30/git-commit-analyzer/releases

Git Commit Analyzer is a Rust-based Git plugin that generates Conventional Commits messages from your staged diff using a local llama.cpp model. The CLI summarises large diffs, validates model output, and falls back to deterministic messages when needed.

Key Features

• Local inference: Uses llama_cpp_sys_2 to run GGUF models without any remote API calls.
• Any-device model tiers: Auto-selects small / default / quality Qwen3 GGUFs from system memory (4K–16K context; /no_think for fast structured output).
• Hierarchical diff packing: Multi-file commits keep an inventory + key signatures before filling leftover budget with snippets.
• Conventional Commits validation: Ensures responses match <type>(<scope>): <subject> and retries/falls back when they don't.
• Interactive CLI: Review, edit, or cancel the generated commit message.
• Multi-language prompts: English (default) and Simplified Chinese.
• Multi-platform support: Pre-built binaries for macOS (Intel & Apple Silicon).

Requirements

• Git 2.30+
• A local GGUF model (the CLI can auto-download a Qwen3 tier from Hugging Face)

Installation

Homebrew (Recommended) - Fast Binary Installation

macOS users can install via Homebrew with pre-built binaries (no Rust compilation required):

brew tap zh30/tap
brew install git-ca

This installs a pre-built binary for your platform:

• macOS: Apple Silicon (M1/M2/M3/M4) and Intel (x86_64)

No Rust toolchain or compilation needed! The binary is automatically downloaded from GitHub Releases.

Note: If you encounter a version mismatch error, try:

brew update
brew upgrade git-ca

Or install from source:

brew install --build-from-source git-ca

Linux builds are temporarily disabled due to compilation issues. Windows builds are available via GitHub Releases but not distributed via Homebrew.

Manual Installation

Download the appropriate binary for your platform from Releases:

# macOS (Apple Silicon)
curl -L -o git-ca.tar.gz https://github.com/zh30/git-commit-analyzer/releases/download/v2.0.12/git-ca-2.0.12-apple-darwin-arm64.tar.gz
tar -xzf git-ca.tar.gz
sudo mv git-ca /usr/local/bin/
chmod +x /usr/local/bin/git-ca

Note: Linux builds are temporarily disabled. Windows builds are available via GitHub Releases.

Build from Source

If you prefer to build from source:

git clone https://github.com/zh30/git-commit-analyzer.git
cd git-commit-analyzer
cargo build --release
sudo cp target/release/git-ca /usr/local/bin/

One-Line Bootstrap Script

bash -c "$(curl -fsSL https://sh.zhanghe.dev/install-git-ca.sh)"

First-Time Setup

On first run the CLI will:

1. Probe system memory and recommend a model tier:

   • small (Qwen3-0.6B) — low-RAM / older machines, ~4K context
   • default (Qwen3-1.7B) — balanced, ~8K context
   • quality (Qwen3-4B) — higher quality when memory allows, ~16K context

2. Scan for models in common directories:

   • ./models (project directory)
   • ~/.cache/git-ca/models (Linux/macOS)
   • ~/.local/share/git-ca/models (Linux alt)
   • ~/Library/Application Support/git-ca/models (macOS)

3. Download a tier model automatically if none found (Q4 GGUF from Hugging Face into ~/.cache/git-ca/models/).

4. Prompt interactively when multiple models/tiers are available:

   git ca model              # Interactive selector (tiers + local GGUFs)
   git ca model pull         # Auto-download recommended tier
   git ca model pull quality # Force a specific tier

Usage

git add <files>
git ca

For each invocation:

1. The staged diff is packed hierarchically (file inventory → key signatures → extra snippets) to fit the adaptive context window.
2. The llama.cpp model generates a commit message.
3. Invalid output triggers a stricter retry with a tighter diff view; if still invalid, a deterministic fallback is offered.
4. Choose to use, edit, or cancel the message.

Configuration Commands

• git ca model — Interactive model / tier selector
• git ca model pull [small|default|quality|<repo>] — Download a tier or custom HF GGUF repo
• git ca language — Choose English or Simplified Chinese prompts
• git ca doctor — Hardware profile + model loading smoke test
• git ca --version — Display version information

Optional git config overrides:

git config --global commit-analyzer.model-tier default   # small | default | quality
git config --global commit-analyzer.context 8192         # token context length

Development

cargo fmt
cargo clippy -- -D warnings
cargo test
cargo run -- git ca      # try against staged changes

Key modules:

• src/main.rs — CLI orchestration, diff summariser, fallback generator.
• src/llama.rs — llama.cpp session management.

Release Process

Fully automated release via GitHub Actions:

1. Push a version tag: git tag v1.1.2 && git push origin v1.1.2
2. GitHub Actions automatically:
   • Builds binaries for macOS (Intel & Apple Silicon)
   • Creates GitHub Release with changelog
   • Generates SHA256 checksums
   • Automatically updates Homebrew formula with bottle checksums
   • Pushes updates to homebrew-tap repository
3. Users can immediately install with: brew install git-ca

Note: Linux builds are temporarily disabled due to compilation issues. Windows builds are available via GitHub Releases but not distributed via Homebrew.

See DEPLOY.md for complete release documentation.

Supported Platforms

• macOS: ✅ Apple Silicon (arm64) and Intel (x86_64) - Pre-built binaries via Homebrew
• Linux: ❌ Temporarily disabled (compilation issues)
• Windows: ⚠️ Available via GitHub Releases (not Homebrew)

Contributing

Pull requests are welcome. Please include:

• cargo fmt / cargo clippy -- -D warnings / cargo test outputs,
• Updates to documentation (README*.md, AGENTS.md, DEPLOY.md) when behaviour changes,
• A short description of manual git ca verification if applicable.

License

Released under the MIT License. See LICENSE for details.

Acknowledgments

• The Rust community for providing excellent libraries and tools
• llama.cpp team for the efficient local inference engine