GitViz

GitViz is a terminal-based Git workflow visualizer with an optional SVG graph exporter.
It lets you explore your repository history interactively in the terminal (TUI) or generate clean, themed SVG graphs for documentation, presentations, or analysis.

> Think git log --graph, but readable, interactive, and exportable.

---

Features

- Interactive TUI
- Scrollable commit list
- Per-branch colored lanes
- Commit details panel (author, date, parents)
- Fast fuzzy search (/) by hash, author, or subject
- Themes
- dark (default)
- light
- matrix
- Same theme system used by TUI and SVG
- SVG export
- Curved edges with arrowheads
- Merge commits visually emphasized
- Per-lane colors
- Grid layout for easy reading
- Commit labels rendered directly in the graph
- Fast & local
- Uses git log directly
- No daemon, no background services
- Flexible filtering
- Author
- Date ranges
- File paths
- Commit limits

---

Installation

$3

``bash
pnpm install -g @nolly-cafe/gitviz
``

This installs the CLI command:

`bash
gitviz --help
`

$3

`bash
npx @nolly-cafe/gitviz
`

---

Usage

Run inside any Git repository.

$3

`bash
gitviz --help
`

$3

`bash
gitviz --theme dark
gitviz --theme light
gitviz --theme matrix
`

$3

`bash
gitviz --limit 100
`

$3

`bash
gitviz --author "Nolly"
gitviz --since 2025-01-01
gitviz --until 2026-01-26
gitviz --file src/index.ts
`

Filters can be combined.

---

TUI Controls

| Key | Action |
| ----- | ----------------------------- |
| ↑ / ↓ | Move selection |
| / | Search (hash / author / text) |
| Enter | Confirm search |
| Esc | Cancel search |
| q | Quit |

---

SVG Export

Generate a themed SVG graph of your repository history.

$3

`bash
gitviz --export-svg graph.svg
`

$3

`bash
gitviz --export-svg graph-dark.svg --theme dark
gitviz --export-svg graph-light.svg --theme light
gitviz --export-svg graph-matrix.svg --theme matrix
`

$3

`bash
gitviz --export-svg graph.svg --limit 50 --since 2024-01-01
`

The resulting SVG:

* Is fully self-contained
* Uses valid XML
* Can be opened in browsers, Inkscape, Illustrator, Figma, etc.
* Scales cleanly at any resolution

---

Example Output

$3

* Colored branch lanes
* Clear commit subjects
* Side panel with commit metadata

$3

* Vertical time axis
* Curved parent → child edges
* Merge commits visually highlighted
* Commit subjects rendered inline
* Grid lines for easy scanning

Perfect for:

* README files
* Architecture docs
* Release notes
* Presentations

---

Themes

Currently available themes:

* dark (default)
* light
* matrix

Themes control:

* Background / foreground colors
* Lane colors
* Grid visibility
* Font family
* Node sizing

More themes can be added easily by extending src/theme.ts.

---

Requirements

* Node.js 18+
* Git installed and available in PATH
* A Git repository

---

Philosophy

GitViz is not meant to replace full Git GUIs.

It is designed to be:

* Lightweight
* Scriptable
* Terminal-friendly
* Documentation-friendly (SVG export)

Use it when you want:

* A fast mental model of history
A graph you can share*
* Zero setup overhead

---

Roadmap

* Horizontal (time-left → right) SVG layout
* Per-branch labels
* Interactive SVG (hover / click)
* Config file support
* Custom user-defined themes

---

License

MIT

---

Credits

Inspired by:

* git log --graph`
* Ink (React for CLIs)

Built with ❤️ for developers who live in the terminal.