# CommitLoom 🧵
> Weave perfect git commits with AI-powered intelligence
[](https://badge.fury.io/py/commitloom)
[](https://pypi.org/project/commitloom)
[](https://opensource.org/licenses/MIT)
[](https://codecov.io/github/Arakiss/commitloom)
[](https://github.com/Arakiss/commitloom/actions/workflows/ci.yml)
[](https://github.com/astral-sh/ruff)
[](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 or UV:
```bash
# Using pip
pip install commitloom
# Using UV (faster alternative)
uv add commitloom
# or for global installation
uvx 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 File Grouping**: Advanced semantic analysis to group related files intelligently based on functionality, relationships, and change types
- 🧵 **Smart Batching**: Weaves multiple changes into coherent, logical commits using intelligent grouping algorithms
- 📊 **Complexity Analysis**: Identifies when commits are getting too large or complex
- 🌿 **Branch Suggestions**: Offers to create a new branch for very large commits
- 💰 **Cost Control**: Built-in token and cost estimation to keep API usage efficient
- 📈 **Usage Metrics**: Track your usage, cost savings, and productivity gains with built-in metrics
- 🔍 **Binary Support**: Special handling for binary files with size and type detection
- ⚡ **UV Support**: Compatible with UV package manager for faster dependency management
- 🎨 **Beautiful CLI**: Rich, colorful interface with clear insights and warnings
## 🧠 Smart File Grouping
CommitLoom v1.6.0+ includes advanced semantic analysis for intelligent file grouping. Instead of simple directory-based batching, it now:
### How It Works
- **Change Type Detection**: Automatically identifies the type of changes (features, fixes, tests, docs, refactoring, etc.)
- **File Relationship Analysis**: Detects relationships between files:
- Test files and their corresponding implementation files
- Component files that work together (e.g., component + styles + tests)
- Configuration files and their dependent modules
- Documentation files and related code
- **Semantic Grouping**: Groups files based on functionality rather than just directory structure
- **Confidence Scoring**: Each grouping decision is scored for reliability
### Benefits
- **Better Commit Organization**: Related changes are grouped together logically
- **Cleaner History**: More meaningful commit messages that reflect actual feature boundaries
- **Reduced Context Switching**: Files that belong together are committed together
- **Intelligent Defaults**: Works automatically but can be disabled with `--no-smart-grouping`
### Example
```bash
# Before: Files grouped by directory
Commit 1: src/components/Button.tsx, src/components/Input.tsx
Commit 2: tests/Button.test.tsx, tests/Input.test.tsx
# After: Files grouped by functionality
Commit 1: src/components/Button.tsx, tests/Button.test.tsx, docs/Button.md
Commit 2: src/components/Input.tsx, tests/Input.test.tsx, docs/Input.md
```
## 📖 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
### Recent Major Updates
**v1.6.0+ (2024)**: Introduced intelligent file grouping and performance improvements:
- **Smart File Grouping**: Advanced semantic analysis for better commit organization
- **UV Package Manager Support**: Migrated from Poetry to UV for 10-100x faster dependency management
- **Enhanced CLI**: New `-s/--smart-grouping` and `--no-smart-grouping` options
- **Improved Error Handling**: Better JSON parsing and metrics collection
- **Performance Optimizations**: Reduced logging verbosity and duplicate messages
## ⚙️ 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 [command] [options]
# Using the short alias
cl [command] [options]
```
#### Available Commands
- `loom commit` (or simply `loom`): Generate a commit message and commit your changes
- `loom stats`: Display detailed usage statistics and metrics
#### Options
- `-y, --yes`: Auto-confirm all prompts (non-interactive mode)
- `-c, --combine`: Combine all changes into a single commit
- `-s, --smart-grouping`: Enable intelligent file grouping (default: enabled)
- `--no-smart-grouping`: Disable smart grouping and use simple batching
- `-d, --debug`: Enable debug logging
- `-m, --model`: Specify the AI model to use (e.g., gpt-4.1-mini)
#### Usage Examples
```bash
# Basic usage (interactive mode with smart grouping)
loom
# Non-interactive mode with combined commits
loom -y -c
# Use smart grouping with specific model
loom -s -m gpt-4.1
# Disable smart grouping for simple batching
loom --no-smart-grouping
# View usage statistics
loom stats
# View debug information with statistics
loom stats -d
```
### 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 any OpenAI model for commit message generation. You can specify any model name (e.g., `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, etc.) using the `MODEL_NAME` or `COMMITLOOM_MODEL` environment variable, or with the `-m`/`--model` CLI option.
| Model | Description | Input (per 1M tokens) | Output (per 1M tokens) | Best for |
|-----------------|------------------------------------|-----------------------|------------------------|-------------------------|
| gpt-4.1 | Highest quality, 1M ctx, multimodal| $2.00 | $8.00 | Final docs, critical |
| gpt-4.1-mini | Default, best cost/quality | $0.40 | $1.60 | Most use cases |
| gpt-4.1-nano | Fastest, cheapest | $0.10 | $0.40 | Drafts, previews |
| gpt-4o-mini | Legacy, cost-efficient | $0.15 | $0.60 | Legacy/compatibility |
| gpt-4o | Legacy, powerful | $2.50 | $10.00 | Legacy/compatibility |
| gpt-3.5-turbo | Legacy, fine-tuned | $3.00 | $6.00 | Training data |
| gpt-4o-2024-05-13| Legacy, previous version | $5.00 | $15.00 | Legacy support |
> **Default model:** `gpt-4.1-mini` (best balance for documentation and code)
> **Warning:** If you use a model that is not in the above list, CommitLoom will still work, but cost estimation and token pricing will not be available for that model. You will see a warning in the CLI, and cost will be reported as zero. To add cost support for a new model, update the `model_costs` dictionary in `commitloom/config/settings.py`.
You can change the model by setting the `MODEL_NAME` environment variable. The default `gpt-4.1-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/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-4.1-mini model, costs are very low:
- Input: $0.40 per million tokens
- Output: $1.60 per million tokens
For perspective, a typical commit analysis:
- Uses ~1,000-2,000 tokens
- Costs less than $0.004 (0.4 cents)
- That's about 250 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 track metrics and usage statistics?
CommitLoom keeps track of various metrics to help you understand your usage patterns:
- **Usage tracking**: Number of commits generated, tokens used, and associated costs
- **Time savings**: Estimated time saved compared to writing commit messages manually
- **Repository statistics**: Which repositories you use CommitLoom with most frequently
- **Model usage**: Performance metrics for different AI models
- **Cost analysis**: Detailed breakdown of token usage and associated costs
All metrics are stored locally in your user data directory (`~/.local/share/commitloom/metrics` on Linux) and are never sent to external servers.
To view your metrics, simply run:
```bash
loom stats
```
For detailed documentation on the metrics system, see the [Usage Metrics Documentation](docs/usage_metrics/README.md).
### How does CommitLoom handle large changes?
CommitLoom automatically:
1. Analyzes the size and complexity of changes
2. Uses smart grouping to organize related files together
3. Warns about potentially oversized commits
4. Suggests splitting changes when appropriate
5. Maintains context across split commits
6. Optionally creates a new branch when commits are very large
### What is smart grouping and how does it work?
Smart grouping is CommitLoom's advanced semantic analysis feature that intelligently organizes your changed files:
- **Detects relationships**: Groups test files with their implementation files, components with their styles, etc.
- **Understands change types**: Identifies whether changes are features, fixes, documentation, tests, or refactoring
- **Semantic analysis**: Goes beyond directory structure to understand what files actually work together
- **Automatic by default**: Enabled automatically in v1.6.0+, but can be disabled with `--no-smart-grouping`
This results in more logical commits where related files are grouped together, making your git history cleaner and more meaningful.
## 🛠️ Development Status
- ✅ **CI/CD**: Automated testing, linting, and publishing with GitHub Actions
- ✅ **Package Management**: Migrated to UV for faster dependency resolution and builds
- ✅ **Code Quality**:
- Ruff for linting and formatting
- MyPy for static type checking
- 70%+ test coverage with pytest
- ✅ **Smart Features**: Advanced semantic analysis and intelligent file grouping
- ✅ **Distribution**: Available on PyPI and GitHub Releases
- ✅ **Documentation**: Comprehensive README with feature examples 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": null,
"name": "commitloom",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, cli, commit, git, git-tools, openai, semantic-commits",
"author": null,
"author_email": "Petru Arakiss <petruarakiss@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/60/df/d5101753973e7c37272ba18601b666cb8898ea82b3253a8481bcd1ac899a/commitloom-1.6.2.tar.gz",
"platform": null,
"description": "# CommitLoom \ud83e\uddf5\n\n> Weave perfect git commits with AI-powered intelligence\n\n[](https://badge.fury.io/py/commitloom)\n[](https://pypi.org/project/commitloom)\n[](https://opensource.org/licenses/MIT)\n[](https://codecov.io/github/Arakiss/commitloom)\n[](https://github.com/Arakiss/commitloom/actions/workflows/ci.yml)\n[](https://github.com/astral-sh/ruff)\n[](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 or UV:\n\n```bash\n# Using pip\npip install commitloom\n\n# Using UV (faster alternative)\nuv add commitloom\n# or for global installation\nuvx 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\udde0 **Smart File Grouping**: Advanced semantic analysis to group related files intelligently based on functionality, relationships, and change types\n- \ud83e\uddf5 **Smart Batching**: Weaves multiple changes into coherent, logical commits using intelligent grouping algorithms\n- \ud83d\udcca **Complexity Analysis**: Identifies when commits are getting too large or complex\n- \ud83c\udf3f **Branch Suggestions**: Offers to create a new branch for very large commits\n- \ud83d\udcb0 **Cost Control**: Built-in token and cost estimation to keep API usage efficient\n- \ud83d\udcc8 **Usage Metrics**: Track your usage, cost savings, and productivity gains with built-in metrics\n- \ud83d\udd0d **Binary Support**: Special handling for binary files with size and type detection\n- \u26a1 **UV Support**: Compatible with UV package manager for faster dependency management\n- \ud83c\udfa8 **Beautiful CLI**: Rich, colorful interface with clear insights and warnings\n\n## \ud83e\udde0 Smart File Grouping\n\nCommitLoom v1.6.0+ includes advanced semantic analysis for intelligent file grouping. Instead of simple directory-based batching, it now:\n\n### How It Works\n- **Change Type Detection**: Automatically identifies the type of changes (features, fixes, tests, docs, refactoring, etc.)\n- **File Relationship Analysis**: Detects relationships between files:\n - Test files and their corresponding implementation files\n - Component files that work together (e.g., component + styles + tests)\n - Configuration files and their dependent modules\n - Documentation files and related code\n- **Semantic Grouping**: Groups files based on functionality rather than just directory structure\n- **Confidence Scoring**: Each grouping decision is scored for reliability\n\n### Benefits\n- **Better Commit Organization**: Related changes are grouped together logically\n- **Cleaner History**: More meaningful commit messages that reflect actual feature boundaries\n- **Reduced Context Switching**: Files that belong together are committed together\n- **Intelligent Defaults**: Works automatically but can be disabled with `--no-smart-grouping`\n\n### Example\n```bash\n# Before: Files grouped by directory\nCommit 1: src/components/Button.tsx, src/components/Input.tsx\nCommit 2: tests/Button.test.tsx, tests/Input.test.tsx\n\n# After: Files grouped by functionality \nCommit 1: src/components/Button.tsx, tests/Button.test.tsx, docs/Button.md\nCommit 2: src/components/Input.tsx, tests/Input.test.tsx, docs/Input.md\n```\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### Recent Major Updates\n\n**v1.6.0+ (2024)**: Introduced intelligent file grouping and performance improvements:\n- **Smart File Grouping**: Advanced semantic analysis for better commit organization\n- **UV Package Manager Support**: Migrated from Poetry to UV for 10-100x faster dependency management\n- **Enhanced CLI**: New `-s/--smart-grouping` and `--no-smart-grouping` options\n- **Improved Error Handling**: Better JSON parsing and metrics collection\n- **Performance Optimizations**: Reduced logging verbosity and duplicate messages\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 [command] [options]\n\n# Using the short alias\ncl [command] [options]\n```\n\n#### Available Commands\n\n- `loom commit` (or simply `loom`): Generate a commit message and commit your changes\n- `loom stats`: Display detailed usage statistics and metrics\n\n#### Options\n\n- `-y, --yes`: Auto-confirm all prompts (non-interactive mode)\n- `-c, --combine`: Combine all changes into a single commit\n- `-s, --smart-grouping`: Enable intelligent file grouping (default: enabled)\n- `--no-smart-grouping`: Disable smart grouping and use simple batching\n- `-d, --debug`: Enable debug logging\n- `-m, --model`: Specify the AI model to use (e.g., gpt-4.1-mini)\n\n#### Usage Examples\n\n```bash\n# Basic usage (interactive mode with smart grouping)\nloom\n\n# Non-interactive mode with combined commits\nloom -y -c\n\n# Use smart grouping with specific model\nloom -s -m gpt-4.1\n\n# Disable smart grouping for simple batching\nloom --no-smart-grouping\n\n# View usage statistics\nloom stats\n\n# View debug information with statistics\nloom stats -d\n```\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 any OpenAI model for commit message generation. You can specify any model name (e.g., `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, etc.) using the `MODEL_NAME` or `COMMITLOOM_MODEL` environment variable, or with the `-m`/`--model` CLI option.\n\n| Model | Description | Input (per 1M tokens) | Output (per 1M tokens) | Best for |\n|-----------------|------------------------------------|-----------------------|------------------------|-------------------------|\n| gpt-4.1 | Highest quality, 1M ctx, multimodal| $2.00 | $8.00 | Final docs, critical |\n| gpt-4.1-mini | Default, best cost/quality | $0.40 | $1.60 | Most use cases |\n| gpt-4.1-nano | Fastest, cheapest | $0.10 | $0.40 | Drafts, previews |\n| gpt-4o-mini | Legacy, cost-efficient | $0.15 | $0.60 | Legacy/compatibility |\n| gpt-4o | Legacy, powerful | $2.50 | $10.00 | Legacy/compatibility |\n| gpt-3.5-turbo | Legacy, fine-tuned | $3.00 | $6.00 | Training data |\n| gpt-4o-2024-05-13| Legacy, previous version | $5.00 | $15.00 | Legacy support |\n\n> **Default model:** `gpt-4.1-mini` (best balance for documentation and code)\n\n> **Warning:** If you use a model that is not in the above list, CommitLoom will still work, but cost estimation and token pricing will not be available for that model. You will see a warning in the CLI, and cost will be reported as zero. To add cost support for a new model, update the `model_costs` dictionary in `commitloom/config/settings.py`.\n\nYou can change the model by setting the `MODEL_NAME` environment variable. The default `gpt-4.1-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/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-4.1-mini model, costs are very low:\n- Input: $0.40 per million tokens \n- Output: $1.60 per million tokens\n\nFor perspective, a typical commit analysis:\n- Uses ~1,000-2,000 tokens\n- Costs less than $0.004 (0.4 cents)\n- That's about 250 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 track metrics and usage statistics?\n\nCommitLoom keeps track of various metrics to help you understand your usage patterns:\n\n- **Usage tracking**: Number of commits generated, tokens used, and associated costs\n- **Time savings**: Estimated time saved compared to writing commit messages manually\n- **Repository statistics**: Which repositories you use CommitLoom with most frequently\n- **Model usage**: Performance metrics for different AI models\n- **Cost analysis**: Detailed breakdown of token usage and associated costs\n\nAll metrics are stored locally in your user data directory (`~/.local/share/commitloom/metrics` on Linux) and are never sent to external servers.\n\nTo view your metrics, simply run:\n```bash\nloom stats\n```\n\nFor detailed documentation on the metrics system, see the [Usage Metrics Documentation](docs/usage_metrics/README.md).\n\n### How does CommitLoom handle large changes?\n\nCommitLoom automatically:\n1. Analyzes the size and complexity of changes\n2. Uses smart grouping to organize related files together\n3. Warns about potentially oversized commits\n4. Suggests splitting changes when appropriate\n5. Maintains context across split commits\n6. Optionally creates a new branch when commits are very large\n\n### What is smart grouping and how does it work?\n\nSmart grouping is CommitLoom's advanced semantic analysis feature that intelligently organizes your changed files:\n\n- **Detects relationships**: Groups test files with their implementation files, components with their styles, etc.\n- **Understands change types**: Identifies whether changes are features, fixes, documentation, tests, or refactoring\n- **Semantic analysis**: Goes beyond directory structure to understand what files actually work together\n- **Automatic by default**: Enabled automatically in v1.6.0+, but can be disabled with `--no-smart-grouping`\n\nThis results in more logical commits where related files are grouped together, making your git history cleaner and more meaningful.\n\n## \ud83d\udee0\ufe0f Development Status\n\n- \u2705 **CI/CD**: Automated testing, linting, and publishing with GitHub Actions\n- \u2705 **Package Management**: Migrated to UV for faster dependency resolution and builds\n- \u2705 **Code Quality**: \n - Ruff for linting and formatting\n - MyPy for static type checking\n - 70%+ test coverage with pytest\n- \u2705 **Smart Features**: Advanced semantic analysis and intelligent file grouping\n- \u2705 **Distribution**: Available on PyPI and GitHub Releases\n- \u2705 **Documentation**: Comprehensive README with feature examples 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",
"bugtrack_url": null,
"license": "MIT",
"summary": "Weave perfect git commits with AI-powered intelligence",
"version": "1.6.2",
"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": [
"ai",
" cli",
" commit",
" git",
" git-tools",
" openai",
" semantic-commits"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1e1fdb763b3a09cbb84f3adced847cf9c34864c7c551424b02324369d114b34c",
"md5": "db569e0bbcdb2f2f6c12827da0094460",
"sha256": "48b9e33b61e73bb4f43000435c2df489b2caac1967714db4d53adbeb6bfde2f5"
},
"downloads": -1,
"filename": "commitloom-1.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "db569e0bbcdb2f2f6c12827da0094460",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 38139,
"upload_time": "2025-08-21T21:34:22",
"upload_time_iso_8601": "2025-08-21T21:34:22.360611Z",
"url": "https://files.pythonhosted.org/packages/1e/1f/db763b3a09cbb84f3adced847cf9c34864c7c551424b02324369d114b34c/commitloom-1.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "60dfd5101753973e7c37272ba18601b666cb8898ea82b3253a8481bcd1ac899a",
"md5": "0c67e2ef870d078be3cd6433d1d2b8d8",
"sha256": "bf3d43f32073cfccecc654242d3d082ba75543f6dae5758c4e23381c5ac5d9b2"
},
"downloads": -1,
"filename": "commitloom-1.6.2.tar.gz",
"has_sig": false,
"md5_digest": "0c67e2ef870d078be3cd6433d1d2b8d8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 89908,
"upload_time": "2025-08-21T21:34:23",
"upload_time_iso_8601": "2025-08-21T21:34:23.455851Z",
"url": "https://files.pythonhosted.org/packages/60/df/d5101753973e7c37272ba18601b666cb8898ea82b3253a8481bcd1ac899a/commitloom-1.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 21:34:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Arakiss",
"github_project": "commitloom",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "commitloom"
}
JSON
