Metadata-Version: 2.4
Name: gitaid
Version: 0.4.0
Summary: AI-powered aid for Git
Author-email: Athira <athira.srivani@gmail.com>
License-Expression: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: click
Requires-Dist: openai
Requires-Dist: keyring
Requires-Dist: pyyaml
Requires-Dist: loguru
Requires-Dist: pydantic
Requires-Dist: requests
Dynamic: license-file

<div align="center">

<img src="assets/logo.png" alt="GitAid logo" width="150" />

# GitAid

### AI-powered Git productivity tool from [MayaAI](https://github.com/mayaailabs)

### Commit smarter. Audit history. Understand your codebase - all from the CLI.

[![PyPI version](https://img.shields.io/pypi/v/gitaid)](https://pypi.org/project/gitaid/)
[![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
[![uv](https://img.shields.io/badge/deps-uv-6E56CF)](https://docs.astral.sh/uv/)
[![License](https://img.shields.io/badge/License-Apache%202.0-D22128?logo=apache&logoColor=white)](LICENSE.txt)
[![GitHub](https://img.shields.io/badge/GitHub-Repository-181717?logo=github&logoColor=white)](https://github.com/mayaailabs/gitaid)

</div>

---

> **A note on this project**
>
> GitAid was built at a time when AI-assisted Git workflows weren't yet a standard part of developer tooling - before Cursor, GitHub Copilot, and similar tools had made this kind of thing ubiquitous. The goal was simple: stop context-switching just to write a commit message.
>
> Since then, the landscape has shifted fast. AI coding assistants now handle most of what GitAid was built to solve, often more seamlessly and without a separate install. Rather than compete with that, I'm archiving this project as a snapshot of a genuinely useful idea at the right moment.
>
> If you're looking for something lightweight and terminal-native that still works without a full IDE, GitAid is here. Otherwise - your coding assistant probably already has you covered.
>
> - Athira, MayaAI

---

## Features

- **AI-generated commit messages:** Instantly create clear, context-aware commit messages for your staged changes.
- **Smart commit splitting:** Automatically group staged changes into logical commits, each with its own AI-generated message.
- **Commit auditing:** Audit any commit for message quality, diff hygiene, and alignment with its Jira ticket.
- **History changelog:** Summarize the last N commits as a grouped, human-readable changelog.
- **Empathetic blame:** `gitaid blame` groups lines by commit and explains the intent behind each section.
- **File history narrative:** `gitaid why` explains how a file evolved across its entire commit history.
- **Code change explanations:** Get professional, readable summaries of your staged Git diff.
- **Jira integration across all commands:** Issue keys in commit messages are detected automatically and used to enrich every command's output.
- **Commit message rules:** Define your own format and style rules per repo using `.gitaid-rules.md`.
- **Multi-provider support:** Works with OpenAI, Azure OpenAI, and any OpenAI-compatible API (e.g. vLLM).
- **Tab-completion support:** Shell autocompletion for Bash, Zsh, and Git Bash via Click.

---

## Requirements

- Python 3.9+
- An API key for an OpenAI-compatible LLM provider

---

## Installation

```sh
pip install gitaid
```

Or with [uv](https://docs.astral.sh/uv/):

```sh
uv add gitaid
```

---

## Setup

Run the interactive setup wizard to configure your LLM provider:

```sh
gitaid setup
```

This will prompt you to choose a provider (OpenAI, Azure OpenAI, or a custom vLLM-compatible URL), validate your credentials, and store your API key securely in the OS keyring. Provider and model settings are saved to `~/.gitaid.yml`.

> **Note:** GitAid currently supports only OpenAI-compatible APIs.

To set up a Jira or GitHub Issues integration, run:

```sh
gitaid issues
```

---

## Usage

```sh
git add <files>
gitaid commit
```

For a full list of commands and options:

```sh
gitaid --help
gitaid <command> --help
```

**Staged changes**

| Command | What it does |
|---|---|
| `gitaid commit` | Generate a commit message for your staged changes |
| `gitaid commit --split` | Split staged changes into logical groups and generate a commit message for each |
| `gitaid explain` | Explain your staged changes in plain English |

**History and investigation**

| Command | What it does |
|---|---|
| `gitaid audit` | Audit HEAD for quality, hygiene, and Jira alignment |
| `gitaid audit <commit>` | Audit a specific commit |
| `gitaid history-tldr` | Summarize the last 10 commits as a grouped changelog |
| `gitaid history-tldr --last 20` | Same, for the last N commits |
| `gitaid blame <file>` | Empathetic git blame - explains the intent behind each section |
| `gitaid why <file>` | Narrative of how a file evolved across its entire history |

**Setup**

| Command | What it does |
|---|---|
| `gitaid setup` | Configure your LLM provider (OpenAI, Azure, vLLM) |
| `gitaid issues` | Configure Jira or GitHub Issues integration |

> **Tip: get better results with Jira context**
> All commands that read commit history - `audit`, `history-tldr`, `blame`, `why` -
> automatically detect Jira issue keys in commit messages (e.g. `GA-31`) and fetch
> the ticket's summary, description, and comments to enrich the output.
> Run `gitaid issues` once to configure your tracker. For staged changes, pass
> `--issue GA-31` to `gitaid commit` to pull context at commit time too.

---

## Commit Message Rules

You can define project-specific commit message rules by creating a `.gitaid-rules.md` file in the root of your repository:

```markdown
- Prefix with the Jira issue key when provided: `GA-31: message`
- Keep the subject line under 72 characters
- Use imperative mood: "Add feature" not "Added feature"
- No period at the end of the subject line
```

GitAid will inject these rules into every LLM prompt - both when generating and when reviewing commit messages - so the AI enforces your team's conventions automatically. Commit the file to share the rules across your team.

---

## Configuration

GitAid stores provider and model settings in `~/.gitaid.yml`. This file is written automatically by `gitaid setup`. You can also edit it manually:

```yaml
llm:
  provider: openai
  model: gpt-4o
```

For Azure OpenAI:

```yaml
llm:
  provider: azure
  model: gpt-4o
  base_url: https://your-resource.openai.azure.com
  api_version: "2024-02-01"
```

For a custom vLLM-compatible server:

```yaml
llm:
  provider: vllm
  model: Qwen/Qwen2.5-1.5B-Instruct
  base_url: http://localhost:8000/v1
```

API keys are never stored in this file - they are kept in the OS keyring.

---

## Tab Completion

**Zsh (Linux or Mac):**

```sh
autoload -Uz compinit
compinit
eval "$(_GITAID_COMPLETE=zsh_source gitaid)"
```

Add to `~/.zshrc` to persist.

**Bash (Linux, Bash 4.4+):**

```sh
eval "$(_GITAID_COMPLETE=bash_source gitaid)"
```

Add to `~/.bashrc` to persist.

**Git Bash (Windows):**

```sh
eval "$(_GITAID_COMPLETE=bash_source gitaid)"
```

Add to `~/.bash_profile` to persist.

---

## Why GitAid?

- **Save time:** Let AI handle commit hygiene so you can focus on the code.
- **Improve quality:** Consistent, clear commit messages across your whole team.
- **Stay in context:** Pull Jira or GitHub issue details directly into your commit - no tab switching.
- **Enforce standards:** Define your team's rules once in `.gitaid-rules.md` and let the AI enforce them.

---

## Roadmap

- Automatic test detection and coverage suggestions
- Support for monorepo and multi-repo workflows
- Advanced pre-commit hook integration
- GitHub Issues context fetch (currently Jira only)

---

## License

[Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)
