# Commit Companion
[](https://pypi.org/project/commit-companion/)
[](https://github.com/nelson-zack/commit-companion/releases)
[](https://pepy.tech/project/commit-companion)
[](https://pypi.org/project/commit-companion/)
[](LICENSE)
**AI-powered Git commit assistant that summarizes staged changes using GPT.**
Save time, stay in flow, and write better commit messages — automatically.
---
## Features
- Uses GPT to summarize your staged diffs into clear commit messages
- Supports [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
- Tone customization (`neutral`, `casual`, `formal`, `funny`, etc.)
- Git hook integration via `prepare-commit-msg`
- Supports environment variables for default `TYPE` and `TONE`
- Optional auto mode to skip confirmation (for non-interactive use)
---
## Quick Start
### 1. Install via pip (recommended):
```bash
pip install commit-companion
```
Or, to install from source:
```bash
git clone https://github.com/nelson-zack/commit-companion.git
cd commit-companion
pip install .
```
### 2. Add your OpenAI API key:
Commit Companion requires access to the OpenAI API. You can provide your key in one of two ways:
#### Option 1: `.env` file (for local use)
```bash
OPENAI_API_KEY=sk-...
```
#### Option 2: Environment variable (for global use)
Add to your shell config (`~/.zshrc`, `~/.bashrc`, etc):
```bash
export OPENAI_API_KEY="sk-..."
```
Then run:
```bash
source ~/.zshrc # or ~/.bashrc
```
### 3. Install CLI tool locally:
```bash
pip install --editable .
```
## Requirements
- Python 3.8 or later
- An OpenAI API key (required for GPT functionality)
## Usage
### CLI (manual):
```bash
commit-companion suggest --tone casual --type feat
```
Will output something like:
```bash
feat: add basic functionality to README.md
```
Example usage:
```bash
git add <file>
commit-companion suggest --tone casual --type feat
git commit -m "your message here"
git push
```
### Git Hook (auto):
Install the Git hook with:
```bash
commit-companion install-hook
```
This creates a .git/hooks/prepare-commit-msg script that auto-generates commit messages using GPT.
By default, it uses --tone neutral and --type feat.
#### Once installed, your flow becomes:
```bash
git add <file> # Stage your changes
git commit # Commit Companion will auto-suggest the message
git push # Push to remote
```
#### Customize per commit:
Override tone or type like this:
```bash
TYPE=fix git commit
TONE=funny git commit
TYPE=fix TONE=funny git commit
```
Uninstall the hook:
```bash
commit-companion uninstall-hook
```
### Optional: Global Installation
To use commit-companion from any repo without activating a virtual environment:
#### 1. Install globally:
```bash
pip install .
```
#### 2. Add your OpenAI key to your shell config (~/.zshrc or ~/.bashrc):
```bash
export OPENAI_API_KEY="sk-..."
```
#### 3. Ensure your Python bin path is on your system PATH:
```bash
export PATH="$PATH:/Library/Frameworks/Python.framework/Versions/3.12/bin"
```
#### 4. Reload your shell:
```bash
source ~/.zshrc # or ~/.bashrc
```
#### 5. Use it anywhere:
```bash
commit-companion install-hook
```
## Roadmap Ideas
- Config file support (.commitcompanion.json)
- VS Code extension
- Web version / hosted API
- ✅ PyPI distribution (available via `pip install commit-companion`)
## Why Use This?
Writing commit messages breaks flow. Commit Companion helps you:
- Stay focused on your code
- Standardize commits with no effort
- Impress your teammates with clear, consistent commit messages
## License
MIT License.
## Contributing
Contributions, suggestions, and issue reports are welcome! To get started:
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/my-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin feature/my-feature`)
5. Open a pull request
## Links
- 📦 [PyPI Package](https://pypi.org/project/commit-companion/)
- 🛠 [GitHub Repository](https://github.com/nelson-zack/commit-companion)
- 📝 [Release Notes](https://github.com/nelson-zack/commit-companion/releases)
Raw data
{
"_id": null,
"home_page": null,
"name": "commit-companion",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "git, cli, openai, commit, automation",
"author": null,
"author_email": "Zack Nelson <zacknelson15@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4a/24/90c8e1fae49ed198aa032ed48493c11d1c9758527ecc099ead38e7079caf/commit_companion-0.1.2.tar.gz",
"platform": null,
"description": "# Commit Companion\n\n[](https://pypi.org/project/commit-companion/)\n[](https://github.com/nelson-zack/commit-companion/releases)\n\n[](https://pepy.tech/project/commit-companion)\n[](https://pypi.org/project/commit-companion/)\n\n[](LICENSE)\n\n**AI-powered Git commit assistant that summarizes staged changes using GPT.** \nSave time, stay in flow, and write better commit messages \u2014 automatically.\n\n---\n\n## Features\n\n- Uses GPT to summarize your staged diffs into clear commit messages\n- Supports [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)\n- Tone customization (`neutral`, `casual`, `formal`, `funny`, etc.)\n- Git hook integration via `prepare-commit-msg`\n- Supports environment variables for default `TYPE` and `TONE`\n- Optional auto mode to skip confirmation (for non-interactive use)\n\n---\n\n## Quick Start\n\n### 1. Install via pip (recommended):\n\n```bash\npip install commit-companion\n```\n\nOr, to install from source:\n\n```bash\ngit clone https://github.com/nelson-zack/commit-companion.git\ncd commit-companion\npip install .\n```\n\n### 2. Add your OpenAI API key:\n\nCommit Companion requires access to the OpenAI API. You can provide your key in one of two ways:\n\n#### Option 1: `.env` file (for local use)\n\n```bash\nOPENAI_API_KEY=sk-...\n```\n\n#### Option 2: Environment variable (for global use)\n\nAdd to your shell config (`~/.zshrc`, `~/.bashrc`, etc):\n\n```bash\nexport OPENAI_API_KEY=\"sk-...\"\n```\n\nThen run:\n\n```bash\nsource ~/.zshrc # or ~/.bashrc\n```\n\n### 3. Install CLI tool locally:\n\n```bash\npip install --editable .\n```\n\n## Requirements\n\n- Python 3.8 or later\n- An OpenAI API key (required for GPT functionality)\n\n## Usage\n\n### CLI (manual):\n\n```bash\ncommit-companion suggest --tone casual --type feat\n```\n\nWill output something like:\n\n```bash\nfeat: add basic functionality to README.md\n```\n\nExample usage:\n\n```bash\ngit add <file>\ncommit-companion suggest --tone casual --type feat\ngit commit -m \"your message here\"\ngit push\n```\n\n### Git Hook (auto):\n\nInstall the Git hook with:\n\n```bash\ncommit-companion install-hook\n```\n\nThis creates a .git/hooks/prepare-commit-msg script that auto-generates commit messages using GPT.\nBy default, it uses --tone neutral and --type feat.\n\n#### Once installed, your flow becomes:\n\n```bash\ngit add <file> # Stage your changes\ngit commit # Commit Companion will auto-suggest the message\ngit push # Push to remote\n```\n\n#### Customize per commit:\n\nOverride tone or type like this:\n\n```bash\nTYPE=fix git commit\nTONE=funny git commit\nTYPE=fix TONE=funny git commit\n```\n\nUninstall the hook:\n\n```bash\ncommit-companion uninstall-hook\n```\n\n### Optional: Global Installation\n\nTo use commit-companion from any repo without activating a virtual environment:\n\n#### 1. Install globally:\n\n```bash\npip install .\n```\n\n#### 2. Add your OpenAI key to your shell config (~/.zshrc or ~/.bashrc):\n\n```bash\nexport OPENAI_API_KEY=\"sk-...\"\n```\n\n#### 3. Ensure your Python bin path is on your system PATH:\n\n```bash\nexport PATH=\"$PATH:/Library/Frameworks/Python.framework/Versions/3.12/bin\"\n```\n\n#### 4. Reload your shell:\n\n```bash\nsource ~/.zshrc # or ~/.bashrc\n```\n\n#### 5. Use it anywhere:\n\n```bash\ncommit-companion install-hook\n```\n\n## Roadmap Ideas\n\n- Config file support (.commitcompanion.json)\n- VS Code extension\n- Web version / hosted API\n- \u2705 PyPI distribution (available via `pip install commit-companion`)\n\n## Why Use This?\n\nWriting commit messages breaks flow. Commit Companion helps you:\n\n- Stay focused on your code\n- Standardize commits with no effort\n- Impress your teammates with clear, consistent commit messages\n\n## License\n\nMIT License.\n\n## Contributing\n\nContributions, suggestions, and issue reports are welcome! To get started:\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/my-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin feature/my-feature`)\n5. Open a pull request\n\n## Links\n\n- \ud83d\udce6 [PyPI Package](https://pypi.org/project/commit-companion/)\n- \ud83d\udee0 [GitHub Repository](https://github.com/nelson-zack/commit-companion)\n- \ud83d\udcdd [Release Notes](https://github.com/nelson-zack/commit-companion/releases)\n",
"bugtrack_url": null,
"license": null,
"summary": "Smarter Git commit messages using GPT.",
"version": "0.1.2",
"project_urls": {
"Home": "https://github.com/nelson-zack/commit-companion"
},
"split_keywords": [
"git",
" cli",
" openai",
" commit",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "baedf33b8c8599b5ab6fbbceea31fe5adf4d1e9e61905a309ac25b46a2f25b5a",
"md5": "20c276fcbb0978d4cba3bed4022b7ce4",
"sha256": "cd192da260e2eb0afe491355dded6d13193989f8a7b06179404c3bac173d79de"
},
"downloads": -1,
"filename": "commit_companion-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "20c276fcbb0978d4cba3bed4022b7ce4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7508,
"upload_time": "2025-08-22T21:47:16",
"upload_time_iso_8601": "2025-08-22T21:47:16.406908Z",
"url": "https://files.pythonhosted.org/packages/ba/ed/f33b8c8599b5ab6fbbceea31fe5adf4d1e9e61905a309ac25b46a2f25b5a/commit_companion-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4a2490c8e1fae49ed198aa032ed48493c11d1c9758527ecc099ead38e7079caf",
"md5": "88c480eb07ffd433bcfd93cd631ef9b5",
"sha256": "dd14909e8dd9682633dfd16574a30ff342188f3966fe4885a71ec7f242ded745"
},
"downloads": -1,
"filename": "commit_companion-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "88c480eb07ffd433bcfd93cd631ef9b5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7968,
"upload_time": "2025-08-22T21:47:18",
"upload_time_iso_8601": "2025-08-22T21:47:18.006002Z",
"url": "https://files.pythonhosted.org/packages/4a/24/90c8e1fae49ed198aa032ed48493c11d1c9758527ecc099ead38e7079caf/commit_companion-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 21:47:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nelson-zack",
"github_project": "commit-companion",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "click",
"specs": []
},
{
"name": "openai",
"specs": []
},
{
"name": "python-dotenv",
"specs": []
}
],
"lcname": "commit-companion"
}
JSON
