https://github.com/nazarli-shabnam/git-explain
Commit smarter, not harder. Suggests git add and git commit from your changes-local heuristics or optional AI. Fast, private, and works out of the box.
https://github.com/nazarli-shabnam/git-explain
cli commit-messages developer-tools gemini git python
Last synced: about 18 hours ago
JSON representation
Commit smarter, not harder. Suggests git add and git commit from your changes-local heuristics or optional AI. Fast, private, and works out of the box.
- Host: GitHub
- URL: https://github.com/nazarli-shabnam/git-explain
- Owner: nazarli-shabnam
- License: apache-2.0
- Created: 2026-03-06T05:30:27.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-03-25T05:11:29.000Z (12 days ago)
- Last Synced: 2026-04-03T01:22:24.476Z (3 days ago)
- Topics: cli, commit-messages, developer-tools, gemini, git, python
- Language: Python
- Homepage: https://pypi.org/project/git-explain/
- Size: 84 KB
- Stars: 9
- Watchers: 1
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.
[](https://pypi.org/project/git-explain/)
[](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 .
```
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.
---
## 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 files only**; prints one **`git commit -m "..."`** line for scripting. 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
```