{"id":37072340,"url":"https://github.com/avanrossum/commit-gpt","last_synced_at":"2026-01-14T08:29:36.232Z","repository":{"id":309407077,"uuid":"1036035621","full_name":"avanrossum/commit-gpt","owner":"avanrossum","description":"Uses OpenAI API to help write amazing commit messages","archived":false,"fork":false,"pushed_at":"2025-08-11T20:19:11.000Z","size":103,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-18T02:24:42.414Z","etag":null,"topics":["anthropic-claude","commit","git","openai-api","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/avanrossum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-11T13:14:21.000Z","updated_at":"2025-08-11T20:14:52.000Z","dependencies_parsed_at":"2025-08-11T19:39:47.965Z","dependency_job_id":null,"html_url":"https://github.com/avanrossum/commit-gpt","commit_stats":null,"previous_names":["avanrossum/commit-gpt"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/avanrossum/commit-gpt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avanrossum%2Fcommit-gpt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avanrossum%2Fcommit-gpt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avanrossum%2Fcommit-gpt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avanrossum%2Fcommit-gpt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/avanrossum","download_url":"https://codeload.github.com/avanrossum/commit-gpt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avanrossum%2Fcommit-gpt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28414072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:16:59.381Z","status":"ssl_error","status_checked_at":"2026-01-14T08:13:45.490Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic-claude","commit","git","openai-api","python3"],"created_at":"2026-01-14T08:29:35.712Z","updated_at":"2026-01-14T08:29:36.214Z","avatar_url":"https://github.com/avanrossum.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Commit-GPT\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![CI](https://github.com/avanrossum/commit-gpt/actions/workflows/ci.yml/badge.svg)](https://github.com/avanrossum/commit-gpt/actions/workflows/ci.yml)\n\nAI-powered git commit message generator that turns your staged changes into meaningful commit messages.\n\n⚠️ **Security Notice**: This tool sends git diffs to external AI services. Use `--no-llm` for sensitive code or review [Privacy \u0026 Security](#privacy--security) section.\n\n## Features\n\n- 🤖 **AI-Powered**: Uses OpenAI GPT or Anthropic Claude to generate intelligent commit messages\n- 🔒 **Secure**: Automatically redacts secrets and sensitive data before sending to AI\n- ⚡ **Fast**: Caches responses locally to avoid repeated API calls\n- 🛡️ **Risk Assessment**: Detects potential issues like secrets, destructive changes, and breaking changes\n- 📝 **Flexible**: Supports both conventional commits and casual styles\n- 💰 **Cost Control**: Built-in cost limits and token estimation\n- 🔄 **Offline Fallback**: Heuristic-based generation when no API key is available\n- 🎯 **Smart Orchestration**: Suggests how to split large diffs into multiple focused commits\n\n## Quick Start\n\n### Installation\n\n#### Option 1: Install from PyPI (Recommended)\n```bash\npip install smart-commit-gpt\n```\n\n#### Option 2: Install from Source\n```bash\n# Clone the repository\ngit clone https://github.com/alexvanrossum/commit-gpt.git\ncd commit-gpt\n\n# Install in development mode\npip install -e .\n```\n\n### Setup\n\nSet your API key using a `.env` file (recommended for security):\n\n```bash\n# Create a .env file in your project directory\necho \"OPENAI_API_KEY=your-actual-openai-api-key\" \u003e .env\n\n# Or copy the example file (if installing from source)\ncp .env.example .env\n# Edit .env with your actual API key\n```\n\n**That's it!** Commit-GPT will automatically load the `.env` file when you run it. No need to manually source the file or set environment variables.\n\n**Note**: The `.env` file is already in `.gitignore` to prevent accidental commits of your API key.\n\n**Alternative Setup Methods**:\n- **System Environment**: Add `export OPENAI_API_KEY=\"your-key\"` to your shell profile\n- **Runtime**: Run `OPENAI_API_KEY=your-key commit-gpt`\n- **Virtual Environment**: Set in your venv activation script\n\n### Model Configuration\n\nCommit-GPT supports various GPT-4 series models. Configure via environment variable:\n\n```bash\n# In your .env file\nCOMMIT_GPT_OPENAI_MODEL=gpt-4o  # Default - best balance of quality and cost\nCOMMIT_GPT_OPENAI_MODEL=gpt-4o-mini  # Fastest and cheapest\nCOMMIT_GPT_OPENAI_MODEL=gpt-4.1  # Latest model with large context\nCOMMIT_GPT_OPENAI_MODEL=gpt-4.1-mini  # Good balance for smaller diffs\n```\n\n⚠️ **Model Compatibility**: Using models other than GPT-4 series may result in unexpected behavior due to token limits and context window differences. Recommended models: `gpt-4o`, `gpt-4o-mini`, `gpt-4.1`, `gpt-4.1-mini`.\n\n### Basic Usage\n\n```bash\n# Stage your changes\ngit add .\n\n# Generate commit message\ncommit-gpt\n\n# Write commit directly\ncommit-gpt --write\n```\n\n## Examples\n\n### Conventional Commits (default)\n\n```bash\n$ commit-gpt\nfeat(auth): add refresh token rotation and revoke on logout\n\n- introduce refresh token rotation in oauth2.py\n- add revoke endpoint; update session store\n- adjust tests for new token expiry behavior\n```\n\n### Casual Style\n\n```bash\n$ commit-gpt --style casual\nFix flaky cache warmup and improve error handling\n\n- add retry logic for cache initialization\n- improve error messages for debugging\n- update tests to handle edge cases\n```\n\n### With Explanation\n\n```bash\n$ commit-gpt --explain\nfeat(api): add user authentication endpoints\n\n- implement login and logout routes\n- add JWT token generation and validation\n- include comprehensive test coverage\n\n[explain] $0.0023 :: Generated conventional commit for new authentication feature with proper scope and descriptive body\n```\n\n### Risk Assessment\n\n```bash\n$ commit-gpt --risk-check\nRisk Score: 0.4/1.0 - Found 2 potential secrets; Touches production files: env/prod/\n\nChecklist:\n  🔒 Review for exposed secrets\n  🚨 Review production changes\n```\n\n### Edit Cached Commit Messages\n\n```bash\n# Generate a commit message (cached automatically)\n$ commit-gpt \"add user authentication\"\nfeat: add user authentication system\n\n- implement login and logout functionality\n- add JWT token handling\n- include user session management\n\n# Edit the cached message in your system editor\n$ commit-gpt --amend\n# [Opens your editor with the message above]\n\n# Show the edited message (from cache)\n$ commit-gpt\nfeat: add comprehensive user authentication system\n\n- implement secure login and logout functionality\n- add JWT token generation and validation\n- include user session management with Redis\n- add comprehensive error handling and logging\n\n# Write the edited message to git\n$ commit-gpt -w\n# [Commits with your edited message]\n```\n\n### Complete Workflow Examples\n\n#### **Feature Development Workflow**\n\n```bash\n# 1. Start working on a feature\ngit add src/auth.py src/models.py\n\n# 2. Generate initial commit message\ncommit-gpt \"implement user authentication\"\nfeat: implement user authentication system\n\n- add user model with secure password hashing\n- implement login and registration endpoints\n- add JWT token generation and validation\n\n# 3. Realize you want to add more details\ncommit-gpt --amend\n# [Edit in VS Code: add more context about security features]\n\n# 4. Review the updated message\ncommit-gpt\nfeat: implement secure user authentication system\n\n- add user model with bcrypt password hashing\n- implement login and registration endpoints with rate limiting\n- add JWT token generation and validation with refresh tokens\n- include comprehensive input validation and error handling\n- add audit logging for security events\n\n# 5. Commit when satisfied\ncommit-gpt -w\n```\n\n#### **Bug Fix Workflow**\n\n```bash\n# 1. Fix a bug\ngit add src/bugfix.py\n\n# 2. Generate fix message\ncommit-gpt \"fix authentication bug\"\nfix: resolve token refresh race condition\n\n- prevent multiple simultaneous token refresh requests\n- add request deduplication using Redis locks\n- improve error handling for concurrent requests\n\n# 3. Add more technical details\ncommit-gpt --amend\n# [Add specific details about the race condition]\n\n# 4. Final review and commit\ncommit-gpt -w\n```\n\n#### **Large Change Workflow**\n\n```bash\n# 1. Make significant changes\ngit add .\n\n# 2. Generate comprehensive message\ncommit-gpt \"refactor entire authentication system\"\nfeat: refactor authentication system for better security\n\n- migrate from JWT to session-based authentication\n- implement CSRF protection and rate limiting\n- add comprehensive audit logging\n- update all authentication endpoints\n- include new security middleware\n\n# 3. Split into smaller commits (if needed)\ncommit-gpt --suggest-groups\n[INFO] Large diff detected (15,000 tokens). Suggested commit groups:\n\nGroup 1 (3,200 tokens):\n  Files: src/auth/models.py, src/auth/schemas.py\n\nGroup 2 (4,100 tokens):\n  Files: src/auth/endpoints.py, src/auth/middleware.py\n\nGroup 3 (2,800 tokens):\n  Files: tests/auth/test_models.py, tests/auth/test_endpoints.py\n\n# 4. Commit each group separately\ngit reset HEAD~  # Unstage all changes\ngit add src/auth/models.py src/auth/schemas.py\ncommit-gpt \"add new auth models\" -w\n\ngit add src/auth/endpoints.py src/auth/middleware.py\ncommit-gpt \"implement auth endpoints\" -w\n\ngit add tests/auth/\ncommit-gpt \"add auth tests\" -w\n```\n\n## How It Works\n\n### Caching System\n\nCommit-GPT uses intelligent caching to avoid repeated API calls:\n\n- **Cache Location**: `~/.commit-gpt/cache.db` (SQLite)\n- **Cache Key**: Hash of the entire prompt (diff + context + style)\n- **Cache Hit**: Same staged changes → No API call, instant response\n- **Cache Miss**: Different changes → New API call, cached for next time\n\n### Typical Workflow\n\n```bash\n# First run - API call, cached\ncommit-gpt \"add feature\"\n# [explain] $0.1491 :: Generated with AI\n# feat: add new feature\n\n# Same staged changes - CACHE HIT! No API call\ncommit-gpt \"add feature\"  \n# [explain] $0.0000 :: Using cached response\n# feat: add new feature\n\n# Edit the cached message\ncommit-gpt --amend\n# [Opens editor, edit message]\n\n# Show edited message - Still cache hit!\ncommit-gpt\n# feat: add comprehensive new feature with tests\n\n# Write to git - Still cache hit!\ncommit-gpt -w\n# [Commits with edited message]\n```\n\n### Editor Integration\n\nThe `--amend` feature opens your system editor:\n\n- **VS Code**: `code --wait --new-window`\n- **Vim**: `vim`\n- **Nano**: `nano`\n- **Custom**: Set `$EDITOR` environment variable\n\n## Advanced Usage\n\n### Generate PR Summary\n\n```bash\n$ commit-gpt --pr\nfeat(dashboard): add real-time metrics and alerting\n\n- implement WebSocket connection for live updates\n- add alert configuration UI\n- integrate with monitoring services\n\nPR_TITLE: Add Real-time Dashboard with Alerting System\nPR_SUMMARY:\n- Live metrics display with WebSocket updates\n- Configurable alert thresholds and notifications\n- Integration with existing monitoring infrastructure\n```\n\n### Analyze Specific Range\n\n```bash\n$ commit-gpt --range HEAD~3..HEAD\nrefactor(core): consolidate database connection handling\n\n- extract connection pool logic into separate module\n- add connection retry and timeout configuration\n- update all database access to use new interface\n```\n\n### Offline Mode\n\n```bash\n$ commit-gpt --no-llm\nfeat(auth): add user authentication module\n\n- modify 3 file(s)\n- add 45 line(s)\n- remove 12 line(s)\n```\n\n### Cost Control\n\n```bash\n$ commit-gpt --max-$ 0.01\n# Will fail if estimated cost exceeds $0.01\n```\n\n### Large Diff Orchestration\n\n```bash\n$ commit-gpt --suggest-groups\n# Suggests how to split large changes into multiple focused commits\n```\n\n### Large Diff Orchestration\n\nFor large changes, commit-gpt can suggest how to split them into multiple focused commits:\n\n```bash\n$ commit-gpt --suggest-groups\n📋 Large diff detected (52837 chars). Suggested commit groups:\n\nGroup 1 (662 chars):\n  Files: .env.example\n  Suggested: chore: Add .env.example with API key placeholders\n\nGroup 2 (3259 chars):\n  Files: ci.yml\n  Suggested: feat: add CI workflow for testing and coverage\n\n💡 To commit each group separately:\n  1. git reset HEAD~  # Unstage all changes\n  2. Stage files for each group: git add \u003cfiles\u003e\n  3. Run commit-gpt for each group\n```\n\nThis creates a cleaner commit history with atomic, focused commits instead of one massive change.\n\n## Configuration\n\n### Environment Variables\n\n- `OPENAI_API_KEY`: Your OpenAI API key\n- `ANTHROPIC_API_KEY`: Your Anthropic API key\n- `COMMIT_GPT_CACHE_DIR`: Custom cache directory (default: `~/.commit-gpt/`)\n\n### Git Hooks\n\n#### Prepare Commit Message Hook\n\n```bash\n# .git/hooks/prepare-commit-msg\n#!/bin/sh\ncommit-gpt \u003e \"$1\"\n```\n\n#### Commit Message Validation\n\n```bash\n# .git/hooks/commit-msg\n#!/bin/sh\ncommit-gpt --validate \u003c \"$1\" || exit 1\n```\n\n## Risk Assessment\n\nCommit-GPT automatically detects potential issues:\n\n- 🔒 **Secrets**: API keys, passwords, private keys\n- ⚠️ **Destructive Changes**: DROP statements, file deletions\n- 🚨 **Production Touches**: Changes to prod configs\n- 💥 **Breaking Changes**: API version bumps, breaking change indicators\n- 🗑️ **Large Deletions**: Bulk file or code removals\n- 🧪 **Test Removals**: Deletion of test files\n- 🗄️ **Migrations**: Database schema changes\n\n## Privacy \u0026 Security\n\n⚠️ **Important Security Notice**: This tool sends your git diffs to external AI services (OpenAI/Anthropic). While we implement redaction to remove common secrets, you should:\n\n- **Review your diffs** before using this tool\n- **Never use on highly sensitive code** without thorough review\n- **Consider using `--no-llm` mode** for sensitive repositories\n- **Understand that redaction is not perfect** - some sensitive data might still be sent\n\n### Security Features\n\n- **Local Processing**: Diffs are processed locally before sending to AI\n- **Automatic Redaction**: Secrets and sensitive data are automatically redacted\n- **Local Cache**: Responses are cached locally in SQLite\n- **No Data Retention**: No data is stored on external servers beyond the API call\n- **Offline Mode**: Use `--no-llm` for heuristic-based generation without AI\n\n### Redaction Patterns\n\nThe tool automatically redacts:\n- AWS access keys and secrets\n- API keys and tokens\n- JWT tokens\n- Private keys (RSA, SSH, etc.)\n- Database connection strings\n- OAuth tokens\n- Environment files (.env, etc.)\n\n## Development\n\n### Installation\n\n```bash\ngit clone https://github.com/avanrossum/commit-gpt.git\ncd commit-gpt\npip install -e .\n```\n\n### Running Tests\n\n```bash\npytest tests/\n```\n\n### Code Quality\n\n```bash\nblack src/\nisort src/\nmypy src/\nruff check src/\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Support\n\n- 📖 [Documentation](https://github.com/avanrossum/commit-gpt/wiki)\n- 🐛 [Issues](https://github.com/avanrossum/commit-gpt/issues)\n- 💬 [Discussions](https://github.com/avanrossum/commit-gpt/discussions)\n\n---\n\n**Note**: This tool is designed to assist with commit message generation. Always review generated messages before committing, especially for important changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favanrossum%2Fcommit-gpt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favanrossum%2Fcommit-gpt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favanrossum%2Fcommit-gpt/lists"}