Visualization & Export
Commands for generating DOT graphs, PR writeups, and exporting your decision graph for GitHub Pages.
deciduous dot
Export the graph as DOT format for Graphviz visualization.
| Flag | Short | Description |
|---|---|---|
--output <file> | -o | Output file (default: stdout) |
--roots <ids> | -r | Root node IDs (comma-separated, traverses children) |
--nodes <spec> | -n | Node IDs or ranges (e.g., 1-11 or 1,3,5-10) |
--png | Generate PNG using graphviz (requires dot command) | |
--auto | Auto-generate branch-specific filename in docs/ | |
--title <text> | -t | Graph title |
--rankdir <dir> | Graph direction: TB (top-bottom) or LR (left-right). Default: TB |
Basic DOT export
$ deciduous dot -o graph.dot
Generate PNG directly
Requires Graphviz installed (brew install graphviz / apt install graphviz).
Wrote DOT to docs/graph.dot
Generated PNG: docs/graph.png
Filter by node range
Wrote DOT to docs/auth-flow.dot (11 nodes)
Generated PNG: docs/auth-flow.png
$ deciduous dot -r 42 --rankdir LR -t "Auth Decision Tree"
# Outputs DOT to stdout, rooted at node 42, left-to-right layout
Auto-naming for PRs
The --auto flag generates branch-specific filenames (e.g., docs/decision-graph-feature-auth.dot), which prevents merge conflicts when multiple PRs each have their own graph.
Wrote DOT to docs/decision-graph-feature-auth.dot (15 nodes)
Generated PNG: docs/decision-graph-feature-auth.png
deciduous writeup
Generate a PR writeup from the decision graph. Includes a decision summary, the graph in DOT format, and a test plan section.
| Flag | Short | Description |
|---|---|---|
--title <text> | -t | PR title |
--roots <ids> | -r | Root node IDs (comma-separated, traverses children) |
--nodes <spec> | -n | Node IDs or ranges (e.g., 1-11 or 1,3,5-10) |
--output <file> | -o | Output file (default: stdout) |
--png <filename> | PNG filename to embed (auto-detects repo/branch for GitHub URL) | |
--auto | Auto-detect PNG from branch name | |
--no-dot | Skip DOT graph section | |
--no-test-plan | Skip test plan section |
Basic writeup
Wrote PR writeup to PR.md (6 nodes)
Auto-detect PNG for embedding
When you have already generated a PNG with deciduous dot --auto --png, use --auto on writeup to find and embed it:
# Outputs markdown to stdout with embedded graph image
Update a PR body directly
https://github.com/owner/repo/pull/42
deciduous sync
Export graph data to JSON files for GitHub Pages deployment. Creates the files needed for a static version of the web viewer.
| Flag | Short | Description |
|---|---|---|
--output <path> | -o | Output path (default: .deciduous/web/graph-data.json) |
Exported graph to docs/graph-data.json (47 nodes, 52 edges)
Exported git history to docs/git-history.json
Copied viewer to docs/index.html
Ready for GitHub Pages deployment from /docs
The PR Workflow
The recommended workflow for including decision graphs in pull requests:
$ deciduous dot --auto --nodes 1-11 --png
Wrote DOT to docs/decision-graph-feature-auth.dot (11 nodes)
Generated PNG: docs/decision-graph-feature-auth.png
# 2. Commit and push
$ git add docs/decision-graph-feature-auth.dot docs/decision-graph-feature-auth.png
$ git commit -m "docs: add decision graph"
$ git push
# 3. Generate writeup with auto PNG detection
$ deciduous writeup --auto -t "Add Auth" --nodes 1-11
# 4. Update PR body
$ gh pr edit 42 --body "$(deciduous writeup --auto -t 'Add Auth' --nodes 1-11)"
https://github.com/owner/repo/pull/42
GitHub Pages Deployment
To make your decision graph publicly viewable:
- Run
deciduous syncto export - Push the
docs/folder to GitHub - Go to Settings > Pages > Deploy from branch > select
/docsfolder - Your graph will be live at
https://<user>.github.io/<repo>/