# CommitLoom ๐งต
> Weave perfect git commits with AI-powered intelligence
[![PyPI version](https://badge.fury.io/py/commitloom.svg)](https://badge.fury.io/py/commitloom)
[![Python Version](https://img.shields.io/pypi/pyversions/commitloom)](https://pypi.org/project/commitloom)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![codecov](https://codecov.io/github/Arakiss/commitloom/branch/main/graph/badge.svg?token=NH2X51V6IA)](https://codecov.io/github/Arakiss/commitloom)
[![CI](https://github.com/Arakiss/commitloom/actions/workflows/ci.yml/badge.svg)](https://github.com/Arakiss/commitloom/actions/workflows/ci.yml)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
CommitLoom is an intelligent git assistant I created to help developers craft meaningful, structured commits. Like a master weaver's loom, it brings together all the threads of your changes into beautiful, well-organized commits.
## ๐ฏ Why CommitLoom?
As a developer, I found that managing git commits was often challenging:
- Writing clear, descriptive commit messages takes time
- Large changes are hard to organize effectively
- Maintaining consistency across projects is difficult
- Binary files require special attention
I built CommitLoom to solve these challenges by:
- Automatically generating structured commit messages
- Intelligently batching large changes
- Ensuring consistent commit style
- Providing clear insights about your changes
## ๐ Quick Start
1. Install CommitLoom via pip:
```bash
pip install commitloom
```
2. Set up your OpenAI API key:
```bash
export OPENAI_API_KEY=your-api-key
# or create a .env file with OPENAI_API_KEY=your-api-key
```
3. Stage your changes with git:
```bash
git add . # or stage specific files
```
4. Use CommitLoom to create your commit:
```bash
loom # Interactive mode
# or
loom -y # Non-interactive mode
```
## โจ Features
- ๐ค **AI-Powered Analysis**: Intelligently analyzes your changes and generates structured, semantic commit messages
- ๐งต **Smart Batching**: Weaves multiple changes into coherent, logical commits
- ๐ **Complexity Analysis**: Identifies when commits are getting too large or complex
- ๐ฐ **Cost Control**: Built-in token and cost estimation to keep API usage efficient
- ๐ **Binary Support**: Special handling for binary files with size and type detection
- ๐จ **Beautiful CLI**: Rich, colorful interface with clear insights and warnings
## ๐ Project History
CommitLoom evolved from my personal script that I was tired of copying across different projects. Its predecessor, GitMuse, was my experiment with local models like Llama through Ollama, but I couldn't achieve the consistent, high-quality results I needed. The rise of cost-effective OpenAI models, particularly gpt-4o-mini, made it possible for me to create a more reliable and powerful tool.
Key improvements over GitMuse:
- Uses OpenAI's models for superior commit message generation
- More cost-effective with the new gpt-4o-mini model
- Better structured for distribution and maintenance
- Enhanced error handling and user experience
- Improved binary file handling
## โ๏ธ Configuration
CommitLoom offers multiple ways to configure your API key and settings:
### Command Usage
CommitLoom can be invoked using either of these commands:
```bash
# Using the full name
loom [options]
# Using the short alias
cl [options]
```
Both commands support the same options:
- `-y, --yes`: Auto-confirm all prompts (non-interactive mode)
- `-c, --combine`: Combine all changes into a single commit
- `-v, --verbose`: Enable verbose logging
### API Key Configuration
You can set your API key using any of these methods (in order of precedence):
1. Environment variables:
```bash
export OPENAI_API_KEY=your-api-key
# or
export COMMITLOOM_API_KEY=your-api-key
```
2. Project-level `.env` file:
```env
OPENAI_API_KEY=your-api-key
# or
COMMITLOOM_API_KEY=your-api-key
```
3. Global configuration file:
```bash
# Create global config directory
mkdir -p ~/.commitloom
# Store your API key
echo "your-api-key" > ~/.commitloom/config
```
4. Global `.env` file in `~/.commitloom/.env`
### Other Settings
Configure additional settings via environment variables or `.env` files:
```env
# New environment variable names (recommended)
COMMITLOOM_TOKEN_LIMIT=120000
COMMITLOOM_MAX_FILES=5
COMMITLOOM_COST_WARNING=0.05
COMMITLOOM_MODEL=gpt-4o-mini
# Legacy names (still supported)
TOKEN_LIMIT=120000
MAX_FILES_THRESHOLD=5
COST_WARNING_THRESHOLD=0.05
MODEL_NAME=gpt-4o-mini
```
Configuration files are searched in this order:
1. Current working directory `.env`
2. Project root directory `.env`
3. Global `~/.commitloom/.env`
4. System environment variables
### ๐ค Model Configuration
CommitLoom supports various OpenAI models with different cost implications:
| Model | Description | Cost per 1M tokens (Input/Output) | Best for |
|-------|-------------|----------------------------------|----------|
| gpt-4o-mini | Default, optimized for commits | $0.15/$0.60 | Most use cases |
| gpt-4o | Latest model, powerful | $2.50/$10.00 | Complex analysis |
| gpt-4o-2024-05-13 | Previous version | $5.00/$15.00 | Legacy support |
| gpt-3.5-turbo | Fine-tuned version | $3.00/$6.00 | Training data |
You can change the model by setting the `MODEL_NAME` environment variable. The default `gpt-4o-mini` model is recommended as it provides the best balance of cost and quality for commit message generation. It's OpenAI's most cost-efficient small model that's smarter and cheaper than GPT-3.5 Turbo.
> Note: Prices are based on OpenAI's official pricing (https://openai.com/api/pricing/). Batch API usage can provide a 50% discount but responses will be returned within 24 hours.
## โ FAQ
### Why the name "CommitLoom"?
I chose the name to reflect the tool's ability to weave together different aspects of your changes into a coherent commit, like a loom weaving threads into fabric. It emphasizes both the craftsmanship aspect of good commits and the tool's ability to bring structure to complex changes.
### Why use OpenAI instead of local models?
While local models like Llama are impressive, my experience with GitMuse showed that for specialized tasks like commit message generation, OpenAI's models provide superior results. With the introduction of cost-effective models like gpt-4o-mini, I found that the benefits of cloud-based AI outweigh the advantages of local models for this specific use case.
### How much will it cost to use CommitLoom?
With the default gpt-4o-mini model, costs are very low:
- Input: $0.15 per million tokens
- Output: $0.60 per million tokens
For perspective, a typical commit analysis:
- Uses ~1,000-2,000 tokens
- Costs less than $0.002 (0.2 cents)
- That's about 500 commits for $1
This makes it one of the most cost-effective tools in its category, especially when compared to the time saved and quality of commit messages generated.
### Can I use CommitLoom in CI/CD pipelines?
Yes! Use the `-y` flag for non-interactive mode:
```bash
loom -y
```
### How does CommitLoom handle large changes?
CommitLoom automatically:
1. Analyzes the size and complexity of changes
2. Warns about potentially oversized commits
3. Suggests splitting changes when appropriate
4. Maintains context across split commits
## ๐ ๏ธ Development Status
- โ
**CI/CD**: Automated testing, linting, and publishing
- โ
**Code Quality**:
- Ruff for linting and formatting
- MyPy for static type checking
- 70%+ test coverage
- โ
**Distribution**: Available on PyPI and GitHub Releases
- โ
**Documentation**: Comprehensive README and type hints
- โ
**Maintenance**: Actively maintained and accepting contributions
## ๐ค Contributing
While I maintain this project personally, I welcome contributions! If you'd like to help improve CommitLoom, please:
- Check the issues page for current tasks
- Follow the code style guidelines
- Add tests for new features
- Update documentation as needed
See the [Contributing Guidelines](CONTRIBUTING.md) for detailed instructions.
## ๐ License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
<p align="center">Crafted with ๐งต by <a href="https://github.com/Arakiss">@Arakiss</a></p>
Raw data
{
"_id": null,
"home_page": "https://github.com/Arakiss/commitloom",
"name": "commitloom",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "git, commit, ai, openai, cli, git-tools, semantic-commits",
"author": "Petru Arakiss",
"author_email": "petruarakiss@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/56/2d/e469fdd61755b1b658637a65de003125944ed0569c7f32032dc84839e6a8/commitloom-1.0.1.tar.gz",
"platform": null,
"description": "# CommitLoom \ud83e\uddf5\n\n> Weave perfect git commits with AI-powered intelligence\n\n[![PyPI version](https://badge.fury.io/py/commitloom.svg)](https://badge.fury.io/py/commitloom)\n[![Python Version](https://img.shields.io/pypi/pyversions/commitloom)](https://pypi.org/project/commitloom)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![codecov](https://codecov.io/github/Arakiss/commitloom/branch/main/graph/badge.svg?token=NH2X51V6IA)](https://codecov.io/github/Arakiss/commitloom)\n[![CI](https://github.com/Arakiss/commitloom/actions/workflows/ci.yml/badge.svg)](https://github.com/Arakiss/commitloom/actions/workflows/ci.yml)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)\n\nCommitLoom is an intelligent git assistant I created to help developers craft meaningful, structured commits. Like a master weaver's loom, it brings together all the threads of your changes into beautiful, well-organized commits.\n\n## \ud83c\udfaf Why CommitLoom?\n\nAs a developer, I found that managing git commits was often challenging:\n- Writing clear, descriptive commit messages takes time\n- Large changes are hard to organize effectively\n- Maintaining consistency across projects is difficult\n- Binary files require special attention\n\nI built CommitLoom to solve these challenges by:\n- Automatically generating structured commit messages\n- Intelligently batching large changes\n- Ensuring consistent commit style\n- Providing clear insights about your changes\n\n## \ud83d\ude80 Quick Start\n\n1. Install CommitLoom via pip:\n\n```bash\npip install commitloom\n```\n\n2. Set up your OpenAI API key:\n\n```bash\nexport OPENAI_API_KEY=your-api-key\n# or create a .env file with OPENAI_API_KEY=your-api-key\n```\n\n3. Stage your changes with git:\n\n```bash\ngit add . # or stage specific files\n```\n\n4. Use CommitLoom to create your commit:\n\n```bash\nloom # Interactive mode\n# or\nloom -y # Non-interactive mode\n```\n\n## \u2728 Features\n\n- \ud83e\udd16 **AI-Powered Analysis**: Intelligently analyzes your changes and generates structured, semantic commit messages\n- \ud83e\uddf5 **Smart Batching**: Weaves multiple changes into coherent, logical commits\n- \ud83d\udcca **Complexity Analysis**: Identifies when commits are getting too large or complex\n- \ud83d\udcb0 **Cost Control**: Built-in token and cost estimation to keep API usage efficient\n- \ud83d\udd0d **Binary Support**: Special handling for binary files with size and type detection\n- \ud83c\udfa8 **Beautiful CLI**: Rich, colorful interface with clear insights and warnings\n\n## \ud83d\udcd6 Project History\n\nCommitLoom evolved from my personal script that I was tired of copying across different projects. Its predecessor, GitMuse, was my experiment with local models like Llama through Ollama, but I couldn't achieve the consistent, high-quality results I needed. The rise of cost-effective OpenAI models, particularly gpt-4o-mini, made it possible for me to create a more reliable and powerful tool.\n\nKey improvements over GitMuse:\n- Uses OpenAI's models for superior commit message generation\n- More cost-effective with the new gpt-4o-mini model\n- Better structured for distribution and maintenance\n- Enhanced error handling and user experience\n- Improved binary file handling\n\n## \u2699\ufe0f Configuration\n\nCommitLoom offers multiple ways to configure your API key and settings:\n\n### Command Usage\n\nCommitLoom can be invoked using either of these commands:\n\n```bash\n# Using the full name\nloom [options]\n\n# Using the short alias\ncl [options]\n```\n\nBoth commands support the same options:\n- `-y, --yes`: Auto-confirm all prompts (non-interactive mode)\n- `-c, --combine`: Combine all changes into a single commit\n- `-v, --verbose`: Enable verbose logging\n\n### API Key Configuration\n\nYou can set your API key using any of these methods (in order of precedence):\n\n1. Environment variables:\n\n```bash\nexport OPENAI_API_KEY=your-api-key\n# or\nexport COMMITLOOM_API_KEY=your-api-key\n```\n\n2. Project-level `.env` file:\n\n```env\nOPENAI_API_KEY=your-api-key\n# or\nCOMMITLOOM_API_KEY=your-api-key\n```\n\n3. Global configuration file:\n\n```bash\n# Create global config directory\nmkdir -p ~/.commitloom\n# Store your API key\necho \"your-api-key\" > ~/.commitloom/config\n```\n\n4. Global `.env` file in `~/.commitloom/.env`\n\n### Other Settings\n\nConfigure additional settings via environment variables or `.env` files:\n\n```env\n# New environment variable names (recommended)\nCOMMITLOOM_TOKEN_LIMIT=120000\nCOMMITLOOM_MAX_FILES=5\nCOMMITLOOM_COST_WARNING=0.05\nCOMMITLOOM_MODEL=gpt-4o-mini\n\n# Legacy names (still supported)\nTOKEN_LIMIT=120000\nMAX_FILES_THRESHOLD=5\nCOST_WARNING_THRESHOLD=0.05\nMODEL_NAME=gpt-4o-mini\n```\n\nConfiguration files are searched in this order:\n1. Current working directory `.env`\n2. Project root directory `.env`\n3. Global `~/.commitloom/.env`\n4. System environment variables\n\n### \ud83e\udd16 Model Configuration\n\nCommitLoom supports various OpenAI models with different cost implications:\n\n| Model | Description | Cost per 1M tokens (Input/Output) | Best for |\n|-------|-------------|----------------------------------|----------|\n| gpt-4o-mini | Default, optimized for commits | $0.15/$0.60 | Most use cases |\n| gpt-4o | Latest model, powerful | $2.50/$10.00 | Complex analysis |\n| gpt-4o-2024-05-13 | Previous version | $5.00/$15.00 | Legacy support |\n| gpt-3.5-turbo | Fine-tuned version | $3.00/$6.00 | Training data |\n\nYou can change the model by setting the `MODEL_NAME` environment variable. The default `gpt-4o-mini` model is recommended as it provides the best balance of cost and quality for commit message generation. It's OpenAI's most cost-efficient small model that's smarter and cheaper than GPT-3.5 Turbo.\n\n> Note: Prices are based on OpenAI's official pricing (https://openai.com/api/pricing/). Batch API usage can provide a 50% discount but responses will be returned within 24 hours.\n\n## \u2753 FAQ\n\n### Why the name \"CommitLoom\"?\n\nI chose the name to reflect the tool's ability to weave together different aspects of your changes into a coherent commit, like a loom weaving threads into fabric. It emphasizes both the craftsmanship aspect of good commits and the tool's ability to bring structure to complex changes.\n\n### Why use OpenAI instead of local models?\n\nWhile local models like Llama are impressive, my experience with GitMuse showed that for specialized tasks like commit message generation, OpenAI's models provide superior results. With the introduction of cost-effective models like gpt-4o-mini, I found that the benefits of cloud-based AI outweigh the advantages of local models for this specific use case.\n\n### How much will it cost to use CommitLoom?\n\nWith the default gpt-4o-mini model, costs are very low:\n- Input: $0.15 per million tokens\n- Output: $0.60 per million tokens\n\nFor perspective, a typical commit analysis:\n- Uses ~1,000-2,000 tokens\n- Costs less than $0.002 (0.2 cents)\n- That's about 500 commits for $1\n\nThis makes it one of the most cost-effective tools in its category, especially when compared to the time saved and quality of commit messages generated.\n\n### Can I use CommitLoom in CI/CD pipelines?\n\nYes! Use the `-y` flag for non-interactive mode:\n```bash\nloom -y\n```\n\n### How does CommitLoom handle large changes?\n\nCommitLoom automatically:\n1. Analyzes the size and complexity of changes\n2. Warns about potentially oversized commits\n3. Suggests splitting changes when appropriate\n4. Maintains context across split commits\n\n## \ud83d\udee0\ufe0f Development Status\n\n- \u2705 **CI/CD**: Automated testing, linting, and publishing\n- \u2705 **Code Quality**: \n - Ruff for linting and formatting\n - MyPy for static type checking\n - 70%+ test coverage\n- \u2705 **Distribution**: Available on PyPI and GitHub Releases\n- \u2705 **Documentation**: Comprehensive README and type hints\n- \u2705 **Maintenance**: Actively maintained and accepting contributions\n\n## \ud83e\udd1d Contributing\n\nWhile I maintain this project personally, I welcome contributions! If you'd like to help improve CommitLoom, please:\n- Check the issues page for current tasks\n- Follow the code style guidelines\n- Add tests for new features\n- Update documentation as needed\n\nSee the [Contributing Guidelines](CONTRIBUTING.md) for detailed instructions.\n\n## \ud83d\udcdc License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n<p align=\"center\">Crafted with \ud83e\uddf5 by <a href=\"https://github.com/Arakiss\">@Arakiss</a></p>\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Weave perfect git commits with AI-powered intelligence",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/Arakiss/commitloom/issues",
"Documentation": "https://github.com/Arakiss/commitloom#readme",
"Homepage": "https://github.com/Arakiss/commitloom",
"Repository": "https://github.com/Arakiss/commitloom"
},
"split_keywords": [
"git",
" commit",
" ai",
" openai",
" cli",
" git-tools",
" semantic-commits"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4f84dffa8ce11d0b5331914b75fe1a50496b5566a0846c81c2af3a4f52e290b5",
"md5": "7916aed0c9e15806e606f7d49d773c97",
"sha256": "dba018950f1c8aa93df7406079316ba013a12c1804ccd2cc8b8d7e0fb8f15ef2"
},
"downloads": -1,
"filename": "commitloom-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7916aed0c9e15806e606f7d49d773c97",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 22017,
"upload_time": "2024-12-10T05:41:02",
"upload_time_iso_8601": "2024-12-10T05:41:02.721923Z",
"url": "https://files.pythonhosted.org/packages/4f/84/dffa8ce11d0b5331914b75fe1a50496b5566a0846c81c2af3a4f52e290b5/commitloom-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "562de469fdd61755b1b658637a65de003125944ed0569c7f32032dc84839e6a8",
"md5": "1ef3cf080faf3abaccf981e347eaf9c6",
"sha256": "4c433db02bd1b97e5db03d23458f7e09f031247c4d00b1c4b01e5e87d6810d9d"
},
"downloads": -1,
"filename": "commitloom-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "1ef3cf080faf3abaccf981e347eaf9c6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 22103,
"upload_time": "2024-12-10T05:41:06",
"upload_time_iso_8601": "2024-12-10T05:41:06.166215Z",
"url": "https://files.pythonhosted.org/packages/56/2d/e469fdd61755b1b658637a65de003125944ed0569c7f32032dc84839e6a8/commitloom-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-10 05:41:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Arakiss",
"github_project": "commitloom",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "commitloom"
}