Skip to content

gitsvg

A CLI that renders git tree visualizations as SVG from JSONL input.

gitsvg turns a plain-text description of a git history — branches, commits, merges, pull requests — into a clean SVG diagram. The input is a .gitsvg.jsonl file: a list of operations, one JSON object per line, applied top-to-bottom to build the diagram. Because the format is line-oriented and declarative, it is easy for both people and LLM-based agents to author.

PyPI Python License

Installation

pip install gitsvg

Or with uv:

uv tool install gitsvg

Quick start

Write a .gitsvg.jsonl file:

{"op": "branch", "name": "main", "label_side": "before"}
{"op": "commit", "branch": "main", "id": "c1", "msg": "initial commit", "hash": "auto"}
{"op": "commit", "branch": "main", "id": "c2", "msg": "add README", "hash": "auto"}
{"op": "branch", "name": "feature", "from_branch": "main"}
{"op": "commit", "branch": "feature", "id": "f1", "msg": "add login form", "hash": "auto"}
{"op": "merge", "from": "feature", "into": "main", "as": "m1", "msg": "merge feature", "hash": "auto"}

Render it to SVG:

gitsvg render diagram.gitsvg.jsonl -o diagram.svg

Validate without rendering:

gitsvg validate diagram.gitsvg.jsonl

That's the whole loop. See the Examples gallery for the full feature surface — branching, merges, pull requests, theming, orientations, and layout modes — and the Input format page for the operation set.

Where to go next

  • Examples — a gallery of rendered diagrams with their source.
  • CLI reference — every command, including the agent-facing schema / errors / theme introspection commands.
  • Input format — the nine operations and how a diagram is built.
  • Python API — gitsvg.render_text() for embedding gitsvg in other tools.
  • Integrations — the GitHub Action and MkDocs plugin for rendering diagrams in CI and in your docs.