<!-- markdownlint-disable MD013 -->

# 🚀 Git Auto Commit (gac)

[![PyPI version](https://img.shields.io/pypi/v/gac.svg)](https://pypi.org/project/gac/)
[![Python](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13%20|%203.14-blue.svg)](https://www.python.org/downloads/)
[![Build Status](https://github.com/cellwebb/gac/actions/workflows/ci.yml/badge.svg)](https://github.com/cellwebb/gac/actions)
[![codecov](https://codecov.io/gh/cellwebb/gac/branch/main/graph/badge.svg)](https://app.codecov.io/gh/cellwebb/gac)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![mypy](https://img.shields.io/badge/mypy-checked-blue.svg)](https://mypy-lang.org/)
[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](docs/CONTRIBUTING.md)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**LLM-powered commit messages that understand your code.**

**Tired of writing commit messages?** Replace `git commit -m "..."` with `gac` for contextual, well-formatted commit messages generated by large language models.

---

## What You Get

Instead of generic messages like `"update stuff"`, `"fix bug"`, or `"add feature"`, you get intelligent, contextual messages that explain the **why** behind your changes:

![GAC generating a contextual commit message](assets/gac-simple-usage.png)

---

## Quick Start

### Install & Use

```bash
# 1. Install globally
uv tool install gac

# 2. Configure your LLM provider
gac init

# 3. Use on your staged changes
git add .
gac
```

That's it! Review the generated message and confirm with `y`.

### Use without installing

```bash
uvx gac init
uvx gac
```

---

## Key Features

### **Supported Providers**

- **Anthropic** • **Cerebras** • **Chutes.ai** • **Gemini** • **Groq**
- **LM Studio** • **Ollama** • **OpenAI** • **OpenRouter**
- **Streamlake** • **Synthetic.new** • **Z.AI** • **Z.AI Coding**

### **Smart LLM Analysis**

- **Understands intent**: Analyzes code structure, logic, and patterns to understand the "why" behind your changes, not just what changed
- **Semantic awareness**: Recognizes refactoring, bug fixes, features, and breaking changes to generate contextually appropriate messages
- **Intelligent filtering**: Prioritizes meaningful changes while ignoring generated files, dependencies, and artifacts

### **Multiple Message Formats**

- **One-liner** (-o flag): Single-line commit message following conventional commit format
- **Standard** (default): Summary with bullet points explaining implementation details
- **Verbose** (-v flag): Comprehensive explanations including motivation, technical approach, and impact analysis

### **Developer Experience**

- **Interactive feedback**: Regenerate messages with specific requests like `r "make it shorter"` or `r "focus on the bug fix"`
- **One-command workflows**: Complete workflows with flags like `gac -ayp` (stage all, auto-confirm, push)
- **Git integration**: Respects pre-commit and lefthook hooks, running them before expensive LLM operations

### **Built-in Security**

- **Automatic secret detection**: Scans for API keys, passwords, and tokens before committing
- **Interactive protection**: Prompts before committing potentially sensitive data with clear remediation options
- **Smart filtering**: Ignores example files, template files, and placeholder text to reduce false positives

---

## Usage Examples

### Basic Workflow

```bash
# Stage your changes
git add .

# Generate and commit with LLM
gac

# Review → y (commit) | n (cancel) | r (reroll)
```

### Common Commands

| Command         | Description                                    |
| --------------- | ---------------------------------------------- |
| `gac`           | Generate commit message                        |
| `gac -y`        | Auto-confirm (no review needed)                |
| `gac -a`        | Stage all + commit                             |
| `gac -o`        | One-line message only                          |
| `gac -v`        | Detailed verbose format                        |
| `gac -h "hint"` | Add context for LLM (e.g., `gac -h "bug fix"`) |
| `gac -s`        | Include scope (e.g., feat(auth):)              |
| `gac -p`        | Commit and push                                |

### Power User Examples

```bash
# Complete workflow in one command
gac -ayp -h "release preparation"

# Detailed explanation with scope
gac -v -s

# Quick one-liner for small changes
gac -o

# Debug what the LLM sees
gac --show-prompt

# Skip security scan (use carefully)
gac --skip-secret-scan
```

### Interactive Reroll System

Not happy with the result? Use the reroll feature for intelligent regeneration:

```bash
# Simple regeneration (uses previous context)
r

# With specific feedback
r make it shorter and focus on the performance improvement
r use conventional commit format with scope
r explain the security implications
```

---

## Configuration

Run `gac init` to configure your provider interactively, or set environment variables:

```bash
# Example configuration
GAC_MODEL=anthropic:your-model-name
OPENAI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
```

See `.gac.env.example` for all available options.

---

## Getting Help

- **Full documentation**: [USAGE.md](USAGE.md) - Complete CLI reference
- **Troubleshooting**: [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) - Common issues and solutions
- **Contributing**: [CONTRIBUTING.md](docs/CONTRIBUTING.md) - Development setup and guidelines

---

<!-- markdownlint-disable MD033 MD036 -->

<div align="center">

Made with ❤️ for developers who want better commit messages

[⭐ Star us on GitHub](https://github.com/cellwebb/gac) • [🐛 Report issues](https://github.com/cellwebb/gac/issues) • [📖 Full docs](USAGE.md)

</div>

<!-- markdownlint-enable MD033 MD036 -->
