git-auto-commit

AI-powered Git commit message generator that runs locally with Ollama.

git-auto-commit analyzes your repository diff and generates a commit message in a strict PREFIX: description format.

Features

• AI-generated commit messages
• Strict PREFIX: description validation
• Automatic retries for invalid model output
• Diff size limiting to prevent context overflow
• Consolidated or per-file commit mode
• Dry-run mode
• Fully local execution (no external API)

Requirements

• Python 3.11 or 3.12 recommended
• Git
• Ollama running locally

Python 3.14+ is not recommended due to current LangChain compatibility.

Supported Prefixes

• FEAT
• FIX
• REFACTOR
• PERF
• DOCS
• STYLE
• TEST
• CHORE

Expected format:

PREFIX: clear and concise description

Example:

FEAT: add JWT authentication middleware

Installation

1. Install Ollama: https://ollama.com
2. Start Ollama:

ollama serve

3. Pull a recommended model:

ollama pull llama3:8b

4. Clone and install this project:

git clone https://github.com/ViniciusCMB/git-auto-commit.git
cd git-auto-commit
pip install -e .

Usage

Basic usage:

git-auto-commit

Generate a message without committing:

git-auto-commit --dry-run

Use a specific model:

git-auto-commit --model llama3:8b

Limit diff size:

git-auto-commit --max-diff 4000

Commit per file instead of a single consolidated message:

git-auto-commit --per-file

How It Works

1. Reads staged and unstaged changes
2. Truncates the diff if it is too large
3. Sends diff context to a local Ollama model
4. Validates model output against commit format rules
5. Retries up to 3 times when output is invalid
6. Commits if a valid message is produced

Automatic Retry Behavior

If the model output is invalid, the tool:

• Tries to extract the first valid line
• Reinforces formatting instructions
• Retries up to 3 times
• Fails safely if still invalid

This keeps behavior robust even with smaller models such as gemma3:1b.

Recommended Models

• llama3:8b
• qwen2.5:7b
• mistral:7b

Development

Install development tooling:

pip install black pylint

Run formatter:

black git_auto_commit

Run linter:

pylint git_auto_commit

For contribution workflow and roadmap, see CONTRIBUTING.md.

Security

• Uses subprocess without shell=True
• No external API calls
• Repository data remains local

Project Roadmap

• Conventional Commit scopes
• Pre-commit hook integration
• PR summary generation
• CI mode
• Multi-step agent version

Contributing

Pull requests are welcome. See CONTRIBUTING.md for the standard process.

License

MIT License