why-changed

Pipe a git diff, get a plain-language explanation powered by Mistral AI.

![DEMO GIF HERE]

---

Installation

# npm
npm install -g why-changed

# pnpm
pnpm add -g why-changed

# bun
bun add -g why-changed

# yarn
yarn global add why-changed

---

Usage

# Explain the last commit
git diff HEAD~1 | why-changed

# Explain staged changes
git diff --cached | why-changed

# Compare two branches
git diff main..feature/my-branch | why-changed

# Export as Markdown
git diff HEAD~1 | why-changed --format=md

# Export as HTML
git diff HEAD~1 | why-changed --format=html

# Custom output file
git diff HEAD~1 | why-changed --format=html --output=report.html

# Explain in French
git diff HEAD~1 | why-changed --lang=fr

# Disable colors (e.g. for CI logs)
git diff HEAD~1 | why-changed --no-color

Options

Flag	Description	Default
--format	Output format: terminal, md, html	terminal
--lang	Response language (ISO 639-1 code, e.g. fr, es, de, ja)	en
--output	Output file path (for md/html formats)	CHANGES.md / CHANGES.html
--no-color	Disable colored terminal output	—

Output formats

Format	Description
terminal	Coloured output directly in your terminal
md	Markdown file ready to paste into a PR description or wiki
html	Self-contained HTML report with a dark-themed UI

---

API Key

why-changed uses the Mistral AI API. Get a free key at console.mistral.ai, then set it before running:

export MISTRAL_API_KEY=your-key

Or create a .env file at your project root:

MISTRAL_API_KEY=your-key

The .env file is loaded automatically — no extra setup needed.

---

Contributing

Contributions are welcome! Here's how to get started:

git clone https://github.com/Itaromi/why-changed.git
cd why-changed
npm install        # or pnpm install / bun install
cp .env.example .env   # add your MISTRAL_API_KEY
npm run build
git diff HEAD~1 | node bin/why-changed.js

To watch for changes during development:

npx tsc --watch

Bug reports and feature requests → open an issue.

---

License

MIT © Youn Sylvestre

---

Made with ❤️ by Youn Sylvestre