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.

---

Install (Python 3.10+)

pip install git-explain

From source (this repo):

pip install -e .

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

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:

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

---

Try it

1. In any git repo, change or add a file (not ignored).
2. Run:

   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—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.
• 404 / model not found — set something current, e.g. GEMINI_MODEL=gemini-2.5-flash, and check their model list.

---

Developers

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

GitAds Sponsored