🧠 AI-Powered Commit Message Generator

Generate meaningful Git commit messages automatically using the Flan-T5 language model. Works completely offline and is CPU-friendly!

✨ Features

• 🤖 AI-Powered : Uses Google's Flan-T5 model to understand code changes
• 💻 CPU-Friendly : No GPU required, runs on any machine
• 🔒 Offline : Works without internet connection after initial model download
• 📝 Conventional Commits : Supports standard commit types (feat, fix, docs, etc.)
• ⚡ Fast : Generates messages in seconds
• 🎯 Smart : Analyzes actual code changes, not just file names

🚀 Installation

Prerequisites

• Python 3.8 or higher
• Git installed on your system

Setup

1. Clone or download the project :

cd ai-commit-gen

2. Create a virtual environment (recommended):

python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

3. Install dependencies :

pip install -r requirements.txt

4. First run (downloads the model):

python commitgen.py --help

The first time you run the tool, it will download the Flan-T5 model (~240 MB). This is a one-time download.

📖 Usage

Basic Usage

1. Stage your changes :

git add .

2. Generate a commit message :

python commitgen.py

Advanced Usage

Specify commit type :

python commitgen.py --type feat
python commitgen.py --type fix
python commitgen.py --type docs

Add a scope :

python commitgen.py --type feat --scope auth
# Output: feat(auth): added password validation and strength checker

Show the diff being analyzed :

python commitgen.py --show-diff

Auto-commit with generated message :

python commitgen.py --auto-commit

Custom message length :

python commitgen.py --max-length 50

Use a different model :

# Default is flan-t5-small (~240MB)
python commitgen.py --model google/flan-t5-base  # ~900MB, better quality

🎯 Examples

Example 1: Feature Addition

# After adding a new login feature
git add src/auth/login.py
python commitgen.py --type feat --scope auth

# Output: feat(auth): implemented user login with email validation

Example 2: Bug Fix

# After fixing a bug
git add src/api/users.py
python commitgen.py --type fix

# Output: fix: resolved null pointer exception in user data retrieval

Example 3: Documentation

# After updating README
git add README.md
python commitgen.py --type docs

# Output: docs: updated installation instructions and added examples

🔧 Available Commit Types

Following Conventional Commits specification:

• feat: A new feature
• fix: A bug fix
• docs: Documentation changes
• style: Code style changes (formatting, missing semi-colons, etc.)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

💡 Tips for Best Results

1. Stage related changes together : The AI works best when analyzing cohesive changes
2. Use specific file staging : git add specific-file.py for focused messages
3. Review before committing : Always review the generated message
4. Combine with scope : Use --scope to add context (e.g., --scope api)

🛠️ Project Structure

ai-commit-gen/
├── commitgen.py          # Main CLI application
├── utils.py              # Helper functions and model logic
├── requirements.txt      # Python dependencies
├── README.md            # This file
└── examples/
    └── sample_diff.txt  # Example diff for testing

🔍 How It Works

1. Extracts Git diff : Reads your staged changes using git diff --cached
2. Prepares input : Cleans and formats the diff for the AI model
3. AI analysis : Flan-T5 analyzes the changes and generates a summary
4. Formats output : Applies conventional commit formatting
5. Returns message : Displays the generated commit message

⚙️ Configuration

Model Selection

The tool supports different Flan-T5 variants:

Model	Size	Quality	Speed
flan-t5-small	240 MB	Good	Fast
flan-t5-base	900 MB	Better	Medium
flan-t5-large	3 GB	Best	Slow

Default is flan-t5-small for the best balance of size and performance.

Environment Variables

You can set default options via environment variables:

export COMMITGEN_MODEL="google/flan-t5-base"
export COMMITGEN_MAX_LENGTH="50"

🚧 Troubleshooting

"Not a Git repository"

Make sure you're running the tool from within a Git repository.

"No staged changes found"

Stage your changes first with git add <files>.

Model download fails

Check your internet connection. The model needs to be downloaded once.

Out of memory errors

Try using a smaller model:

python commitgen.py --model google/flan-t5-small

🔮 Future Enhancements

• VS Code extension
• Git hook integration (pre-commit)
• GitHub Action
• Custom prompt templates
• Multi-language support
• Commit history analysis
• Support for more LLMs (TinyLlama, etc.)

📝 License

MIT License - Feel free to use and modify!

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest features
• Submit pull requests

📚 Resources

• Conventional Commits
• Flan-T5 Model
• Transformers Library

---

Made with ❤️ for developers who care about good commit messages