{"repo": "can1357/llm-git", "files": {"README.md": {"eaf26c27e69687f829ee1573b38ec91a45ab450f": {"t": 1785674406.5655835, "n": 8572, "h": "2627e660a6b5eb5f", "c": "

\n \"lgit\"\n

\n\n

\n LLM-powered git commit message generator\n

\n\n

\n \"CI\"\n \"PyPI\"\n \"License\"\n \"Python\"\n

\n\n

\n Generates conventional commits from git diffs using Claude AI or any OpenAI-compatible API.
\n Automatic changelog maintenance, multi-commit composition, and full history rewriting.\n

\n\n---\n\n## Features\n\n- **Conventional commits** — Generates properly formatted commit messages with type, scope, and past-tense summary (≤72 chars)\n- **Automatic changelogs** — Maintains `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com) format with monorepo support\n- **Compose mode** — Splits large staged changes into multiple logical atomic commits\n- **Rewrite mode** — Converts entire git history to conventional commits (with automatic backup)\n- **Map-reduce analysis** — Parallel per-file analysis for large commits without truncation\n- **Any LLM provider** — Works with Anthropic, OpenAI, OpenRouter, or any OpenAI-compatible API\n\n## Quick Start\n\n```bash\n# Install\nuv tool install lgit-cli\n\n# Configure (pick one)\nexport LLM_GIT_API_KEY=your_anthropic_key # Direct Anthropic\nexport LLM_GIT_API_URL=https://openrouter.ai/api/v1 # OpenRouter\nlitellm --port 4000 # Local proxy (default)\n\n# Use\ngit add .\nlgit # Analyze, update changelog, commit\nlgit --dry-run # Preview without committing\nlgit --compose # Split into multiple commits\n```\n\n## Usage\n\n### Basic Commands\n\n```bash\nlgit # Analyze staged changes and commit\nlgit --dry-run # Preview message without committing\nlgit --copy # Copy message to clipboard\nlgit -p # Commit and push\nlgit -S # GPG sign the commit\nlgit -s # Add Signed-off-by trailer\nlgit --amend # Amend the previous commit\nlgit > msg.txt # Save raw message to file (auto-detected pipe mode)\nlgit --dry-run | git commit -F - # Generate message and commit with custom git flags\n\n# Modes\nlgit --mode=unstaged # Preview unstaged changes (no commit)\nlgit --mode=commit --target=HEAD~1 # Analyze a specific commit\n\n# Models\nlgit -m opus # Use Opus for analysis (more capable)\nlgit -m sonnet # Use Sonnet (default)\n\n# Context\nlgit Fixed regression from PR #123 # Add context via trailing text\nlgit --fixes 123 456 # Add \"Fixes #123, #456\" to body\nlgit --breaking # Mark as breaking change\n```\n\n### Compose Mode\n\nSplit staged changes into multiple logical commits:\n\n```bash\nlgit --compose # Propose and create atomic commits\nlgit --compose --compose-preview # Preview splits without committing\nlgit --compose --compose-max-commits 5\nlgit --compose --compose-test-after-each\n```\n\n### Rewrite Mode\n\nConvert repository history to conventional commits:\n\n```bash\nlgit --rewrite # Rewrite full history (creates backup)\nlgit --rewrite --rewrite-preview 10 # Preview first 10 commits\nlgit --rewrite --rewrite-dry-run # Show all changes without applying\nlgit --rewrite --rewrite-start main~50 # Rewrite last 50 commits only\nlgit --rewrite --rewrite-parallel 20 # 20 concurrent API calls\n```\n\n### Profiling Trace\n\nWrite detailed tracing spans and HTTP timing events to a JSONL file:\n\n```bash\nlgit --trace-output /tmp/lgit-profile.jsonl --dry-run\nLLM_GIT_TRACE_FILE=/tmp/lgit-profile.jsonl lgit --compose\n```\n\nEach span close event includes busy/idle timing from `tracing-subscriber`; API events also record TTFT, total response time, status, and response size.\n\n## Automatic Changelog\n\nlgit automatically maintains `CHANGELOG.md` files when committing:\n\n- **Auto-detection** — Finds all `CHANGELOG.md` files in your repository\n- **Monorepo support** — Routes changes to the correct changelog based on file paths\n- **Deduplication** — Skips entries semantically similar to existing ones\n- **Category mapping** — Maps commit types to sections (Added, Fixed, Changed, etc.)\n\n```\nproject/\n├── CHANGELOG.md ← covers: src/, docs/\n├── packages/\n│ ├── core/\n│ │ └── CHANGELOG.md ← covers: packages/core/**\n│ └── cli/\n│ └── CHANGELOG.md ← covers: packages/cli/**\n```\n\nDisable with `--no-changelog` or `changelog_enabled = false` in config.\n\n## Configuration\n\nCreate `~/.config/llm-git/config.toml`:\n\n```toml\n# API\napi_base_url = \"http://localhost:4000\" # Default: LiteLLM proxy\napi_key = \"sk-...\" # Or use LLM_GIT_API_KEY env var\n\n# Model\nanalysis_model = \"claude-sonnet-4.5\" # Diff analysis / classification\nsummary_model = \"claude-haiku-4-5\" # Summary line generation\n\n# Commit message limits\nsummary_guideline = 72 # Target length\nsummary_soft_limit = 96 # Triggers retry\nsummary_hard_limit = 128 # Absolute max\n\n# Features\nchangelog_enabled = true\nauto_fast_threshold_lines = 200 # Auto-use fast mode for small diffs; 0 disables\nmap_reduce_enabled = true # Parallel analysis for large commits\ndisable_git_background_features = true # Disables fsmonitor/untrackedCache for lgit subprocesses\n\n# Commit signing\ngpg_sign = false # GPG sign commits by default (-S)\nsignoff = false # Add Signed-off-by trailer by default (-s)\n```\n\n### Provider Examples\n\n**Anthropic Direct:**\n```toml\napi_base_url = \"https://api.anthropic.com/v1\"\napi_key = \"sk-ant-...\"\n```\n\n**OpenRouter:**\n```toml\napi_base_url = \"https://openrouter.ai/api/v1\"\napi_key = \"sk-or-...\"\nanalysis_model = \"anthropic/claude-sonnet-4.5\"\nsummary_model = \"anthropic/claude-haiku-4-5\"\n```\n\n**OpenAI:**\n```toml\napi_base_url = \"https://api.openai.com/v1\"\napi_key = \"sk-...\"\nanalysis_model = \"gpt-4o\"\nsummary_model = \"gpt-4o-mini\"\n```\n\nThe client asks all providers for markdown/plain-text responses and parses the same response format across OpenRouter, LiteLLM, Anthropic, and OpenAI endpoints.\n\n### Commit Types\n\nCustomize commit type classification:\n\n```toml\n[types.feat]\ndescription = \"New public API or user-observable behavior change\"\ndiff_indicators = [\"pub fn\", \"pub struct\", \"export function\"]\n\n[types.fix]\ndescription = \"Fixes incorrect behavior\"\ndiff_indicators = [\"unwrap() → ?\", \"bounds check\", \"error handling\"]\n\n[types.refactor]\ndescription = \"Internal restructuring with unchanged behavior\"\nhint = \"If behavior changes, use feat instead.\"\n```\n\n### Changelog Categories\n\n```toml\n[[categories]]\nname = \"Breaking\"\nheader = \"Breaking Changes\"\nmatch.body_contains = [\"breaking\", \"incompatible\"]\n\n[[categories]]\nname = \"Added\"\nmatch.types = [\"feat\"]\n\n[[categories]]\nname = \"Fixed\"\nmatch.types = [\"fix\"]\n\n[[categories]]\nname = \"Changed\"\ndefault = true\n```\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `LLM_GIT_API_URL` | API endpoint | `http://localhost:4000` |\n| `LLM_GIT_API_KEY` | API key | none |\n| `LLM_GIT_CONFIG` | Config file path | `~/.config/llm-git/config.toml` |\n| `LLM_GIT_VERBOSE` | Debug output | `false` |\n| `LLM_GIT_TRACE_FILE` | JSONL profiling trace output path | none |\n\n## Installation\n\n### From PyPI\n\n```bash\nuv tool install lgit-cli # recommended\npipx install lgit-cli # or\npip install lgit-cli\n```\n\n### From source\n\n```bash\ngit clone https://github.com/can1357/llm-git.git\ncd llm-git\nuv tool install .\n```\n\n### Prerequisites\n\n- Python 3.14+\n- Git\n- API access (Anthropic, OpenAI, OpenRouter, or local LiteLLM proxy)\n\n## License\n\nMIT\n"}}}}