gitsvg 0.2.1

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

gitsvg

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

Installation

pip install gitsvg

Or with uv:

uv tool install gitsvg

Quick start

A .gitsvg.jsonl file is a list of operations, one JSON object per line, applied top-to-bottom to build a diagram. Render it with:

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

Validate without rendering:

gitsvg validate diagram.gitsvg.jsonl

Diagrams

The examples/ folder ships ten self-contained input files demonstrating the format. The first seven examples cover the diagram operations; the Theming section below covers visual customisation. Each subsection shows the rendered output and the source it came from.

Example 1: Linear history

A single branch with a few commits. The minimum viable diagram.

{"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": "commit", "branch": "main", "id": "c3", "msg": "add tests", "hash": "auto"}
{"op": "commit", "branch": "main", "id": "c4", "msg": "fix typo", "hash": "auto"}

Example 2: Branch and merge

A feature branch forks off main, accumulates a couple of commits, then merges back.

{"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": "setup config", "hash": "auto"}
{"op": "branch", "name": "feature", "from_branch": "main"}
{"op": "commit", "branch": "feature", "id": "f1", "msg": "add login form", "hash": "auto"}
{"op": "commit", "branch": "feature", "id": "f2", "msg": "wire up auth", "hash": "auto"}
{"op": "merge", "from": "feature", "into": "main", "as": "m1", "msg": "merge feature", "hash": "auto"}

Example 3: Multiple branches with lane reuse

Two concurrent branches share lanes 1 and 2; after both merge, a later feature-b reclaims the now-free lane 1 instead of starting a new one. Lane assignment is automatic and geometry-driven.

{"op": "branch", "name": "main", "label_side": "before"}
{"op": "commit", "branch": "main", "id": "c1", "msg": "initial commit", "hash": "auto"}
{"op": "branch", "name": "feature-a", "from_branch": "main"}
{"op": "commit", "branch": "feature-a", "id": "a1", "msg": "start feature A", "hash": "auto"}
{"op": "branch", "name": "bugfix", "from_branch": "main"}
{"op": "commit", "branch": "bugfix", "id": "x1", "msg": "fix #42", "hash": "auto"}
{"op": "merge", "from": "feature-a", "into": "main", "as": "m1", "msg": "merge feature A", "hash": "auto"}
{"op": "merge", "from": "bugfix", "into": "main", "as": "m2", "msg": "merge bugfix", "hash": "auto"}
{"op": "commit", "branch": "main", "id": "c2", "msg": "release prep", "hash": "auto"}
{"op": "branch", "name": "feature-b", "from_branch": "main"}
{"op": "commit", "branch": "feature-b", "id": "b1", "msg": "feature B", "hash": "auto"}
{"op": "merge", "from": "feature-b", "into": "main", "as": "m3", "msg": "merge feature B", "hash": "auto"}

Example 4: Highlighting a commit

The highlight op marks an existing commit with an enlarged dot and a bold label — useful for drawing attention to a release or a key milestone.

{"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": "feature work", "hash": "auto"}
{"op": "commit", "branch": "main", "id": "c3", "msg": "more feature work", "hash": "auto"}
{"op": "commit", "branch": "main", "id": "v1", "msg": "release v1.0", "hash": "auto"}
{"op": "commit", "branch": "main", "id": "c4", "msg": "post-release fix", "hash": "auto"}
{"op": "highlight", "commit": "v1"}

Example 5: Remove and rebuild (rebase pattern)

A feature branch is removed and re-declared on top of a more recent main commit, with the same commit IDs as before. This is the rebase-style "move my work onto the new tip" pattern, expressed as primitives.

{"op": "branch", "name": "main", "label_side": "before"}
{"op": "commit", "branch": "main", "id": "c1", "msg": "initial commit", "hash": "auto"}
{"op": "branch", "name": "feature", "from_branch": "main"}
{"op": "commit", "branch": "feature", "id": "f1", "msg": "WIP feature", "hash": "auto"}
{"op": "commit", "branch": "feature", "id": "f2", "msg": "more WIP", "hash": "auto"}
{"op": "commit", "branch": "main", "id": "c2", "msg": "main moves on", "hash": "auto"}
{"op": "commit", "branch": "main", "id": "c3", "msg": "more main work", "hash": "auto"}
{"op": "remove", "branches": ["feature"]}
{"op": "branch", "name": "feature", "from_branch": "main"}
{"op": "commit", "branch": "feature", "id": "f1", "msg": "WIP feature", "hash": "auto"}
{"op": "commit", "branch": "feature", "id": "f2", "msg": "more WIP", "hash": "auto"}

Example 6: Import and squash

The import op replays another file as a prelude — here it picks up the rebased state from Example 5. A single new commit then squashes f1 and f2 into one via replaces:.

{"op": "import", "path": "05_remove_rebuild.gitsvg.jsonl"}
{"op": "commit", "branch": "feature", "replaces": ["f1", "f2"], "id": "f_squash", "msg": "complete feature", "hash": "auto"}

Example 7: Open pull request

The pull_request op declares a pending merge between two branches. Both endpoints live-track the current branch tips: as commits accumulate on either side, the dashed arc advances. The optional title renders as a pill anchored at the source-tip commit. The typical lifecycle closes the PR with remove and then runs a real merge; this example stops before either, so the open PR remains visible in the final state.

{"op": "branch", "name": "main", "label_side": "before"}
{"op": "commit", "branch": "main", "id": "m1", "msg": "release"}
{"op": "branch", "name": "feature", "from_branch": "main"}
{"op": "commit", "branch": "feature", "id": "f1", "msg": "wip"}
{"op": "pull_request", "id": "pr1", "from": "feature", "into": "main", "title": "PR 1: add thing"}
{"op": "commit", "branch": "feature", "id": "f2", "msg": "polish"}
{"op": "commit", "branch": "main", "id": "m2", "msg": "hotfix"}

Theming

The theme op customises the diagram's presentational surface — spacings, sizes, fonts, the branch-colour palette, the SVG background, the orientation, and more. Each op only overrides the fields it lists; a name (default, dark, compact) selects a built-in theme to base resolution on.

Example 8: Recoloured palette

Here we import Example 3 unchanged and apply a saturated palette with thicker strokes, larger labels, and a warm background.

{"op": "import", "path": "03_multi_branch.gitsvg.jsonl"}
{"op": "theme", "background_color": "#fff8e7", "branch_spacing": 110, "branch_line_width": 4, "label_font_size": 14, "branch_label_font_size": 14, "hash_font_size": 11, "commit_radius": 7, "highlight_radius": 9, "branch_name_pill_offset_commit_axis_in_rows": -0.56, "colors": {"main": "#d62728", "branch1": "#1f77b4", "branch2": "#2ca02c", "branch3": "#ff7f0e", "branch4": "#9467bd"}}

Example 9: Horizontal orientation

A theme.orientation of lr flips the diagram left-to-right: the commit axis grows rightward and branches stack downward. The same input renders identically in bt (default, bottom-to-top), tb (top-to-bottom), and rl (right-to-left); pill placement, margin defaults, and label-side mapping all adjust per orientation. Accepted values include the canonical short codes (bt, tb, lr, rl) and common aliases (Mermaid's TD, CSS's ltr / rtl, long forms like bottom_to_top, and top_down / bottom_up).

{"op": "branch", "name": "main", "label_side": "before"}
{"op": "commit", "branch": "main", "id": "m1", "msg": "init", "hash": "auto"}
{"op": "commit", "branch": "main", "id": "m2", "msg": "release v1", "hash": "auto", "highlight": true}
{"op": "branch", "name": "feature", "from_branch": "main"}
{"op": "commit", "branch": "feature", "id": "f1", "msg": "wip", "hash": "auto"}
{"op": "commit", "branch": "feature", "id": "f2", "msg": "polish", "hash": "auto"}
{"op": "branch", "name": "docs", "from_branch": "main"}
{"op": "commit", "branch": "docs", "id": "d1", "msg": "readme", "hash": "auto"}
{"op": "merge", "into": "main", "from": "feature", "msg": "merge feature", "hash": "auto"}
{"op": "commit", "branch": "main", "id": "m3", "msg": "hotfix", "hash": "auto"}
{"op": "pull_request", "id": "pr1", "from": "docs", "into": "main", "title": "PR 1: docs update"}
{"op": "theme", "orientation": "lr"}

Named themes

Beyond default, gitsvg ships two built-in themes:

• dark — One Dark-inspired palette on a #282c34 canvas.
• compact — ~30 % denser spacing with smaller fonts.

Selecting one is a single field on a theme op:

{"op": "import", "path": "03_multi_branch.gitsvg.jsonl"}
{"op": "theme", "name": "dark"}

The shipped preview below shows the three built-in themes side-by-side on the same input file:

Selecting a named theme also wipes any theme: field overrides and branch.color overrides accumulated earlier — useful for "use exactly this theme." To layer a chosen theme on top of those overrides instead (e.g. when importing a diagram that already carries its own theming), pass keep_prior_overrides: true on the same op.

CLI reference

Command	Purpose
gitsvg render <input> -o <output>	Render a .gitsvg.jsonl file to SVG. Pass a directory at both ends to recursively walk the input tree and write mirrored .svg outputs under the output directory. --small=N selects minification level 0-3; bare --small is level 2 (lossless structural compression).
gitsvg state <input>	Emit a JSON snapshot of the diagram (branches, commits with their parent chain, open pull requests) — a structural description of the resolved graph. Stdout by default; pass -o <file> to write to a file, or pass a directory pair to recursively walk and emit one <stem>.state.json per input. Output format may change before 1.0; pin a gitsvg version when caching the schema.
gitsvg layout <input>	Emit a JSON view of the resolved layout (grid extent, lane assignments, commit positions, arcs, guides, open pull-request geometry) — what the renderer consumes, useful for debugging visual placement. Same invocation matrix as state (stdout by default, -o <file> for a file, directory pair for recursive walking with <stem>.layout.json outputs). Output format may change before 1.0; pin a gitsvg version when caching the schema.
gitsvg validate <input>	Run the full validation pipeline; report errors with file:line: [code] field: message. Add --json for a structured report.
gitsvg schema	Index of all input operations. gitsvg schema <op> prints the JSON Schema for one operation (e.g. gitsvg schema theme for the theme op's field schema); --list-ops prints a bare op list. gitsvg schema themes lists the registered named themes; gitsvg schema theme <name> prints a named theme's resolved field values.
gitsvg errors	Index of all validation error codes. gitsvg errors <code> prints the long-form catalog entry; --list-codes prints a bare code list.

gitsvg schema and gitsvg errors are designed for agents and tooling: an LLM-based agent producing input can fetch the schema for a single op and the catalog entry for any error it hits, without reading the rest of the documentation.

License

MIT.