gitwit 0.1.0
AI-powered git commit messages, PR descriptions, and changelogs using free APIs
Requires Python: >=3.10
Keywords: ai, cli, commit, gemini, git, groq, llm, ollama

# GitWit

[![PyPI version](https://badge.fury.io/py/gitwit.svg)](https://badge.fury.io/py/gitwit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

**Stop wasting time writing commit messages.** GitWit generates meaningful, conventional commit messages using AI — completely free.

```
$ gitwit commit

Analyzing 3 file(s): +147 -12
Generating commit message using groq (llama-3.3-70b-versatile)...

Generated commit message:

  feat(auth): add OAuth2 login with Google provider

Options: [y]es, [e]dit, [r]egenerate, [n]o/cancel
Accept this message? [y]: y

Committed successfully!
  [main 8f3a2b1] feat(auth): add OAuth2 login with Google provider
```

## Why GitWit?

| Feature | GitWit | aicommits | GitHub Copilot |
|---------|--------|-----------|----------------|
| **Price** | Free forever | Free (limited) | $10/month |
| **API Key** | Free (Groq/Gemini) | Requires OpenAI ($) | Subscription |
| **Local Option** | Yes (Ollama) | No | No |
| **PR Descriptions** | Yes | No | Yes |
| **Conventional Commits** | Yes | Yes | Sometimes |
| **Edit/Regenerate** | Yes | Limited | No |

## Quick Start (3 commands)

```bash
# 1. Install
pip install gitwit

# 2. Configure (one-time, 30 seconds)
gitwit config init

# 3. Use it
git add .
gitwit commit
```

That's it. Your first AI-powered commit in under a minute.

## Features

- **Commit Messages** — Generate conventional commits from staged changes
- **PR Descriptions** — Generate title + description from branch diffs
- **Multiple Providers** — Groq, Google Gemini, or local Ollama
- **Interactive** — Accept, edit, regenerate, or cancel
- **Fast** — Sub-second generation with Groq

## Installation

```bash
pip install gitwit
```

Requires Python 3.10+

## Configuration

### Interactive Setup (Recommended)

```bash
gitwit config init
```

This walks you through choosing a provider and setting your API key.

### Manual Setup

```bash
# Set provider (groq, gemini, or ollama)
gitwit config set provider groq

# Set API key (not needed for Ollama)
gitwit config set api-key YOUR_API_KEY

# View config
gitwit config show
```

## Usage

### Generate Commit Message

```bash
# From staged changes
git add src/
gitwit commit

# Stage all + commit
gitwit commit --all

# Auto-accept (no confirmation)
gitwit commit --yes

# Dry run (preview only)
gitwit commit --dry-run
```

### Generate PR Description

```bash
# Compare current branch to main
gitwit pr

# Specify base branch
gitwit pr --base develop

# Dry run
gitwit pr --dry-run
```

## Why Free?

GitWit uses AI providers with generous free tiers:

| Provider | Free Tier | Speed | Best For |
|----------|-----------|-------|----------|
| **Groq** | 30 req/min | Fastest | Daily use |
| **Gemini** | 1,500 req/day | Fast | High volume |
| **Ollama** | Unlimited | Varies | Privacy, offline |

**Groq** is recommended — it's the fastest inference provider and the free tier is more than enough for individual developers.

### Get Your Free API Key

- **Groq**: [console.groq.com](https://console.groq.com) (instant, no credit card)
- **Gemini**: [aistudio.google.com](https://aistudio.google.com) (instant, no credit card)
- **Ollama**: [ollama.ai](https://ollama.ai) (runs locally, no API key needed)

## How It Works

1. GitWit reads your staged changes (`git diff --cached`)
2. Sends the diff to your chosen AI provider
3. AI generates a conventional commit message
4. You review, edit, regenerate, or accept
5. GitWit runs `git commit` with your approved message

Your code never leaves your machine when using Ollama.

## Contributing

Contributions welcome! Please open an issue or PR.

```bash
# Development setup
git clone https://github.com/MazadiaS/gitwit.git
cd gitwit
pip install -e ".[dev]"
pytest
```

## License

MIT — use it however you want.

---

**Like GitWit?** Give it a ⭐ on [GitHub](https://github.com/MazadiaS/gitwit)!