Metadata-Version: 2.4
Name: git-explain
Version: 2.2.0
Summary: CLI that suggests git add/commit from diffs using Gemini
Author: nazarli-shabnam
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: 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

**Commit message block?** Run this in your repo after you change files. It suggests `git add` and `git commit` lines you can copy—or apply in one step if you want. **Nothing leaves your machine** unless you turn on AI.

[![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)


---

## Install (Python 3.10+)

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

**From source** (this repo):

```bash
pip install -e .
```

**Clone:** install deps (`requirements.txt` is fine), `cd` into the repo, then:

```bash
python -m git_explain
```

Run that from the repo root so Python picks up the `git_explain` folder—no `pip install -e .` needed.

Optional: install a specific tag from GitHub instead of PyPI:

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

---

## Try it

1. In any git repo, change or add a file (not ignored).
2. Run:
   ```bash
   git-explain
   ```
3. Choose what to include (`all` is fine), read the suggestion, answer **`n`** if you only want to copy commands yourself—nothing bad happens.

Heuristics guess a sensible type and message from paths and statuses. **No account, no key, no network** for that path.

Suggested commits follow **[Conventional Commits](https://www.conventionalcommits.org/)**—`feat: …`, `fix: …`, optional `(scope)`, and so on—so changelogs and release tools can read them.

---

## Optional: Gemini

If you want sharper messages, set **`GEMINI_API_KEY`** (or `GOOGLE_API_KEY`) in the environment or a **`.env`** file in the folder where you run the tool.

| Command | In plain terms |
|--------|----------------|
| `git-explain --ai` | AI sees **paths and change type** only (no file contents). |
| `git-explain --ai --with-diff` | AI also sees the **diff**—better detail; only use if you’re OK sending that to the API. |
| `git-explain --suggest` | **Staged only**; prints one plain `git commit -m "…"` line (easy to copy). Needs AI; don’t combine with other flags. |

Everything else (`--auto`, `--staged-only`, `--cwd`, model override, shell completion): **`git-explain --help`**.

---

## If Gemini complains

- **429 / quota** — wait a bit, or try the default model; see Google’s [rate limits](https://ai.google.dev/gemini-api/docs/rate-limits).
- **404 / model not found** — set something current, e.g. **`GEMINI_MODEL=gemini-2.5-flash`**, and check their [model list](https://ai.google.dev/api/models).

---

## Developers

```bash
pip install -e ".[dev]"
pytest -q
```
