{"id":32786667,"url":"https://github.com/blendsdk/git-commit-agent","last_synced_at":"2025-11-11T18:03:40.555Z","repository":{"id":322262095,"uuid":"1088406473","full_name":"blendsdk/git-commit-agent","owner":"blendsdk","description":"🤖 AI-powered git commit message generator using LangChain and OpenAI. Automatically analyzes code changes and creates high-quality conventional commit messages with smart detection, error handling, and global configuration support.","archived":false,"fork":false,"pushed_at":"2025-11-03T13:21:12.000Z","size":134,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-03T15:09:10.873Z","etag":null,"topics":["ai","automation","cli","cli-tools","commit-messages","conventional-commits","developer-tools","git","langchain","openai"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blendsdk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-02T22:38:06.000Z","updated_at":"2025-11-03T13:21:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/blendsdk/git-commit-agent","commit_stats":null,"previous_names":["blendsdk/git-commit-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/blendsdk/git-commit-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fgit-commit-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fgit-commit-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fgit-commit-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fgit-commit-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blendsdk","download_url":"https://codeload.github.com/blendsdk/git-commit-agent/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fgit-commit-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282762578,"owners_count":26723111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-05T02:00:05.946Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai","automation","cli","cli-tools","commit-messages","conventional-commits","developer-tools","git","langchain","openai"],"created_at":"2025-11-05T05:01:30.199Z","updated_at":"2025-11-05T05:02:49.294Z","avatar_url":"https://github.com/blendsdk.png","language":"TypeScript","readme":"# Git Commit Agent\n\nAI-powered git commit message generator using LangChain and OpenAI. Automatically analyzes code changes and creates high-quality conventional commit messages.\n\n## Features\n\n- 🤖 **AI-Powered Analysis** - Uses OpenAI to understand code changes\n- 📝 **Conventional Commits** - Generates standardized commit messages\n- 🔍 **Smart Detection** - Identifies commit type, scope, and impact\n- ⚙️ **Flexible Configuration** - CLI options, environment variables, and global config\n- 🛡️ **Error Handling** - Comprehensive error handling with recovery suggestions\n- 🌍 **Global Configuration** - Support for user-wide settings via `~/.agent-config`\n\n## Installation\n\n### Option 1: NPM/Yarn (Recommended)\n\n```bash\n# Using npm\nnpm install -g @blendsdk/git-commit-agent\n\n# Using yarn\nyarn global add @blendsdk/git-commit-agent\n```\n\n### Option 2: From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/blendsdk/git-commit-agent.git\ncd git-commit-agent\n\n# Install dependencies\nyarn install\n\n# Build\nyarn build\n\n# Link globally for testing\nyarn link\n```\n\n## Quick Start\n\n```bash\n# Navigate to your git repository\ncd your-project\n\n# Make some changes\n# ... edit files ...\n\n# Run the agent\ngit-commit-agent\n```\n\nThe agent will:\n1. Analyze all changes in your repository\n2. Generate a comprehensive conventional commit message\n3. Stage all changes (configurable)\n4. Create the commit with proper multi-line formatting\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file in your project root or `~/.agent-config` in your home directory:\n\n```env\n# Required\nOPENAI_API_KEY=your_openai_api_key_here\n\n# Optional - Model configuration\nOPENAI_MODEL=gpt-4\n\n# Optional - LangChain configuration\nLANGCHAIN_TRACING_V2=true\nLANGCHAIN_API_KEY=your_langchain_api_key\n\n# Optional - Commit format defaults\nCOMMIT_TYPE=feat\nCOMMIT_SCOPE=api\nCOMMIT_SUBJECT_MAX_LENGTH=72\nCOMMIT_DETAIL_LEVEL=normal\nCOMMIT_FILE_BREAKDOWN=true\n\n# Optional - Behavior defaults\nAUTO_STAGE=all\nPUSH=false\nSKIP_VERIFICATION=false\nCONVENTIONAL_STRICT=true\n\n# Optional - Execution defaults\nDRY_RUN=false\nVERBOSE=false\n```\n\n### Global Configuration\n\nFor user-wide settings, create `~/.agent-config`:\n\n```bash\n# Linux/Mac\necho \"OPENAI_API_KEY=your_key_here\" \u003e ~/.agent-config\n\n# Windows\necho OPENAI_API_KEY=your_key_here \u003e %USERPROFILE%\\.agent-config\n```\n\n**Note:** Local `.env` files override global settings.\n\n### Configuration Priority\n\nConfiguration values are merged from three sources:\n\n1. **CLI Arguments** (highest priority)\n2. **Environment Variables** (from `.env` file)\n3. **Built-in Defaults** (lowest priority)\n\n## Usage\n\n### Basic Commands\n\n```bash\n# Use default configuration\ngit-commit-agent\n\n# Preview commit message without committing\ngit-commit-agent --dry-run\n\n# Enable verbose output for debugging\ngit-commit-agent --verbose\n\n# Get help\ngit-commit-agent --help\n\n# Show version\ngit-commit-agent --version\n```\n\n### CLI Options\n\n#### Commit Message Format\n\n**`--commit-type \u003ctype\u003e`**  \nForce a specific commit type instead of letting the agent determine it.\n\nChoices: `feat`, `fix`, `refactor`, `docs`, `test`, `build`, `ci`, `perf`, `style`, `chore`\n\n```bash\ngit-commit-agent --commit-type feat\n```\n\n**`--scope \u003cscope\u003e`**  \nSet the commit scope (e.g., auth, api, ui).\n\n```bash\ngit-commit-agent --scope auth\n```\n\n**`--subject-max-length \u003cnumber\u003e`**  \nMaximum length for the commit subject line (default: 72).\n\n```bash\ngit-commit-agent --subject-max-length 50\n```\n\n**`--detail-level \u003clevel\u003e`**  \nControl the level of detail in the commit message body.\n\nChoices: `brief`, `normal`, `detailed` (default: `normal`)\n\n- `brief`: Minimal description (1-2 sentences)\n- `normal`: Standard description with key changes\n- `detailed`: Comprehensive description with file-by-file breakdown\n\n```bash\ngit-commit-agent --detail-level detailed\n```\n\n**`--file-breakdown` / `--no-file-breakdown`**  \nInclude or exclude file-by-file breakdown in the commit body (default: `true`).\n\n```bash\ngit-commit-agent --no-file-breakdown\n```\n\n#### Behavior Controls\n\n**`--auto-stage \u003cmode\u003e`**  \nControl automatic staging behavior before commit.\n\nChoices: `all`, `modified`, `none` (default: `all`)\n\n- `all`: Stage all changes including untracked files (`git add .`)\n- `modified`: Stage only modified and deleted files (`git add -u`)\n- `none`: Don't stage anything, commit only what's already staged\n\n```bash\ngit-commit-agent --auto-stage modified\n```\n\n**`--push`**  \nPush changes to remote repository after committing (default: `false`).\n\nWhen this flag is set, the system will automatically push the commit to the remote repository after successfully committing locally. Without this flag, commits remain local only.\n\n```bash\ngit-commit-agent --push\n```\n\n**`--no-verify`**  \nSkip commit verification hooks (pre-commit, commit-msg) (default: `false`).\n\n```bash\ngit-commit-agent --no-verify\n```\n\n**`--conventional-strict`**  \nEnforce strict conventional commit format (default: `true`).\n\n```bash\ngit-commit-agent --conventional-strict\n```\n\n#### Execution Options\n\n**`--dry-run`**  \nAnalyze changes and generate commit message without actually committing (default: `false`).\n\n```bash\ngit-commit-agent --dry-run\n```\n\n**`--verbose`**  \nEnable verbose logging to see detailed execution information (default: `false`).\n\n```bash\ngit-commit-agent --verbose\n```\n\n**`--config \u003cpath\u003e`**  \nPath to custom configuration file (future feature).\n\n```bash\ngit-commit-agent --config ./custom-config.json\n```\n\n### Usage Examples\n\n#### Basic Usage\n\n```bash\n# Use all defaults\ngit-commit-agent\n\n# Preview commit message without committing\ngit-commit-agent --dry-run\n\n# Enable verbose output for debugging\ngit-commit-agent --verbose\n```\n\n#### Commit Message Customization\n\n```bash\n# Force specific commit type and scope\ngit-commit-agent --commit-type feat --scope auth\n\n# Brief commit message without file breakdown\ngit-commit-agent --detail-level brief --no-file-breakdown\n\n# Detailed commit with longer subject line\ngit-commit-agent --detail-level detailed --subject-max-length 100\n\n# Quick fix with minimal detail\ngit-commit-agent --commit-type fix --detail-level brief\n```\n\n#### Staging Control\n\n```bash\n# Stage all files including untracked (default)\ngit-commit-agent --auto-stage all\n\n# Only stage modified files\ngit-commit-agent --auto-stage modified\n\n# Only commit already staged files\ngit-commit-agent --auto-stage none\n```\n\n#### Advanced Workflows\n\n```bash\n# Complete workflow: stage all, commit, and push\ngit-commit-agent --auto-stage all --push\n\n# Complete workflow: stage all and commit (without pushing)\ngit-commit-agent --auto-stage all\n\n# Skip pre-commit hooks\ngit-commit-agent --no-verify\n\n# Dry run with verbose output to see what would happen\ngit-commit-agent --dry-run --verbose\n\n# Feature commit with detailed breakdown\ngit-commit-agent --commit-type feat --scope api --detail-level detailed\n```\n\n#### Team Workflows\n\n```bash\n# Consistent brief commits for the team\ngit-commit-agent --detail-level brief --subject-max-length 50\n\n# Detailed commits for major features\ngit-commit-agent --detail-level detailed --commit-type feat\n\n# Quick fixes without verification\ngit-commit-agent --commit-type fix --no-verify --detail-level brief\n```\n\n### Configuration Presets\n\n#### Preset 1: Quick Commits\nFor rapid development with minimal commit messages:\n\n```bash\ngit-commit-agent --detail-level brief --no-file-breakdown\n```\n\nOr in `.env`:\n```env\nCOMMIT_DETAIL_LEVEL=brief\nCOMMIT_FILE_BREAKDOWN=false\nAUTO_STAGE=all\n```\n\n#### Preset 2: Detailed Documentation\nFor comprehensive commit history:\n\n```bash\ngit-commit-agent --detail-level detailed --file-breakdown --subject-max-length 72\n```\n\nOr in `.env`:\n```env\nCOMMIT_DETAIL_LEVEL=detailed\nCOMMIT_FILE_BREAKDOWN=true\nCOMMIT_SUBJECT_MAX_LENGTH=72\n```\n\n#### Preset 3: CI/CD Pipeline\nFor automated commits in CI/CD:\n\n```bash\ngit-commit-agent --auto-stage all --no-verify --push --detail-level normal\n```\n\nOr in `.env`:\n```env\nAUTO_STAGE=all\nSKIP_VERIFICATION=true\nPUSH=true\nCOMMIT_DETAIL_LEVEL=normal\n```\n\n## Commit Message Format\n\nThe agent generates commit messages following the [Conventional Commits](https://www.conventionalcommits.org/) specification:\n\n```\n\u003ctype\u003e(\u003cscope\u003e): \u003csubject\u003e\n\n\u003cbody\u003e\n\n\u003cfooter\u003e\n```\n\n### Commit Types\n\n| Type       | Description                     |\n| ---------- | ------------------------------- |\n| `feat`     | New feature                     |\n| `fix`      | Bug fix                         |\n| `docs`     | Documentation changes           |\n| `style`    | Code style changes (formatting) |\n| `refactor` | Code refactoring                |\n| `perf`     | Performance improvements        |\n| `test`     | Adding or updating tests        |\n| `build`    | Build system changes            |\n| `ci`       | CI configuration changes        |\n| `chore`    | Other changes                   |\n\n### Example Output\n\n```\nfeat(auth): add OAuth2 authentication support\n\n- Implement OAuth2 flow with Google and GitHub providers\n- Add token refresh mechanism\n- Create user session management\n- Update authentication middleware to support OAuth tokens\n\nThis enables users to sign in using their existing social accounts,\nimproving user experience and reducing friction in the signup process.\n\nCloses #234\n```\n\n## Troubleshooting\n\n### \"Not a git repository\" Error\n\nMake sure you're in a git repository:\n\n```bash\ngit init  # If starting a new repo\n```\n\n### \"OPENAI_API_KEY not found\" Error\n\nSet your API key:\n\n```bash\nexport OPENAI_API_KEY=your_key_here\n# Or add to .env file\n```\n\n### \"No changes to commit\" Error\n\nMake sure you have uncommitted changes:\n\n```bash\ngit status  # Check for changes\n```\n\n### Commit message too long\n\nReduce `--subject-max-length` or use `--detail-level brief`:\n\n```bash\ngit-commit-agent --subject-max-length 50 --detail-level brief\n```\n\n### Wrong files staged\n\nUse `--auto-stage none` and manually stage files first:\n\n```bash\ngit add file1.js file2.js\ngit-commit-agent --auto-stage none\n```\n\n### Pre-commit hooks failing\n\nUse `--no-verify` to skip hooks (use cautiously):\n\n```bash\ngit-commit-agent --no-verify\n```\n\n### Need to see what's happening\n\nUse `--verbose` and `--dry-run` together:\n\n```bash\ngit-commit-agent --verbose --dry-run\n```\n\n### Build Errors (when installing from source)\n\n```bash\n# Clear node_modules and reinstall\nrm -rf node_modules yarn.lock\nyarn install\nyarn build\n```\n\n## Tips and Best Practices\n\n1. **Use `.env` for team defaults**: Set common configuration in `.env` and commit it to your repository\n2. **Override with CLI for special cases**: Use CLI arguments for one-off changes\n3. **Dry run first**: Use `--dry-run` to preview the commit message before committing\n4. **Verbose for debugging**: Enable `--verbose` when troubleshooting issues\n5. **Consistent subject length**: Stick to 72 characters for better GitHub display\n6. **Detail level by context**: Use `brief` for small changes, `detailed` for major features\n\n## Documentation\n\n- **[DEVELOPMENT.md](./DEVELOPMENT.md)** - Development guide, architecture, and contributing\n\n## License\n\nISC License - see LICENSE file for details.\n\n## Acknowledgments\n\n- [LangChain](https://github.com/langchain-ai/langchainjs) - Framework for LLM applications\n- [OpenAI](https://openai.com/) - AI model provider\n- [Conventional Commits](https://www.conventionalcommits.org/) - Commit message specification\n\n## Support\n\nFor issues, questions, or contributions, please visit the [GitHub repository](https://github.com/blendsdk/git-commit-agent).\n\n---\n\n**Note:** Remember to replace repository URLs with your actual GitHub repository.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblendsdk%2Fgit-commit-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblendsdk%2Fgit-commit-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblendsdk%2Fgit-commit-agent/lists"}