Metadata-Version: 2.4
Name: git-explain
Version: 2.4.0
Summary: CLI that suggests git add/commit from diffs using Gemini
Author: nazarli-shabnam
Author-email: shabnamnezerli@gmail.com
License-Expression: MIT
Project-URL: Homepage, https://github.com/nazarli-shabnam/git-explain
Project-URL: Source, https://github.com/nazarli-shabnam/git-explain
Keywords: git,cli,commit,ai,gemini
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-genai>=1.50.0
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: prompt_toolkit>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Dynamic: license-file

# git-explain

Suggests **conventional** `git add` / `git commit` messages from your changes. Uses AI when you configure a key; otherwise uses simple local rules.

[![PyPI](https://img.shields.io/pypi/v/git-explain.svg?label=pypi)](https://pypi.org/project/git-explain/)
[![GitHub tag](https://img.shields.io/github/v/tag/nazarli-shabnam/git-explain?label=repo)](https://github.com/nazarli-shabnam/git-explain/tags)
<!-- GitAds-Verify: 29ITVVWNRUVU524NJ5ZRR6DSZKIHP3EX -->

---

## Install and upgrade

```bash
pip install git-explain
pip install --upgrade git-explain
```

Use the second command anytime you want the latest release from PyPI.

In a terminal, go to your project folder (the one that contains `.git`) and run:

```bash
git-explain
```

The first time you run it without `AI_MODEL` in `.env`, the tool can create `.env` with a default Gemini model and a link to create an API key.

---

## Configure (`.env`)

Put a file named **`.env` in the repo root** (next to `.git`). Typical variables:

| Variable | Role |
|----------|------|
| `AI_MODEL` | Gemini model id, e.g. `gemini-2.5-flash`. Set on first run if missing. |
| `AI_API_KEY` | From [Google AI Studio](https://aistudio.google.com/apikey). |
| `AI_MODEL_FALLBACKS` | Optional: comma-separated backup models, tried **in order** after `AI_MODEL` on retryable busy/rate-limit errors. If you omit this variable, the tool uses the **default fallbacks** below. |

**Default `AI_MODEL_FALLBACKS` (when the variable is unset):** `gemini-2.5-flash-lite`, then `gemini-3-flash-preview` — each is tried in sequence after a failed attempt on the previous model in the chain (starting from `AI_MODEL`).

If `AI_API_KEY` is empty, **`GEMINI_API_KEY`** is still read (same key, older name).

---

## Flags

| | |
|--|--|
| `--auto` | Apply suggested commands without a confirmation prompt. |
| `--staged-only` | Work with staged changes only (no `git add` from the tool). |
| `--cwd` | Use another directory as the git repo root. |
| `--with-diff` | Send the full diff to the AI (more context). |
| `--suggest` | Print one suggested `git commit -m "…"` line (staged, AI only). |

If you pick **more than one changed file**, you can choose **one** commit or **split** into several (split is not available with `--staged-only`). **Enter** applies the suggestion; **n** skips so you can copy instead.

Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, optional scope, etc.).

---

## When AI fails

Wrong key, bad model name, network issues, or quota errors → the tool falls back to local heuristics and shows a warning. On retryable busy/rate-limit errors it steps through the fallback chain: your `AI_MODEL` first, then the models in `AI_MODEL_FALLBACKS` (or the **default** `gemini-2.5-flash-lite` → `gemini-3-flash-preview` list if that variable is unset).

---

## Install a specific version from GitHub

```bash
pip install "git+https://github.com/nazarli-shabnam/git-explain.git@v2.3.0"
pip install "git+https://github.com/nazarli-shabnam/git-explain.git@v2.4.0"
```

Replace `v2.3.0` with the [tag](https://github.com/nazarli-shabnam/git-explain/tags) you want.

---

## Develop

From a clone of this repo:

```bash
pip install -r requirements.txt
python -m git_explain
```

Contributors: `pip install -e ".[dev]"` then `pytest -q`, `ruff check .`, `ruff format --check .`.

## GitAds Sponsored
[![Sponsored by GitAds](https://gitads.dev/v1/ad-serve?source=nazarli-shabnam/git-explain@github)](https://gitads.dev/v1/ad-track?source=nazarli-shabnam/git-explain@github)

