Version Visualization

Version Visualization

Setup: See /installation for one-time SDK/CLI/MCP install.
Layers: SDK (Go) → CLI (shell) → MCP (AI tools) — pick your entry point.

When to Use

• Displaying version structure as an ASCII tree for inspection
• Visualizing how versions are grouped and nested
• Generating a summary view showing only group-level information
• Debugging version collections or presenting version info in terminal output

Decision Tree

Need to show individual versions in a tree?
  → Use VisualizeVersions / version_visualize (without --groups)
Collection has many versions and you need a high-level overview?
  → Use VisualizeVersionGroups / version_visualize with groups_only=true
Need to write output to a buffer or file instead of stdout?
  → Use SDK with io.Writer (bytes.Buffer, os.File)
Reading versions from a file?
  → Use --from-file flag (CLI) or ReadVersionsFromFile (SDK) first

Task Patterns

Render a detailed version tree

Goal: Show all versions grouped by major version with individual entries.

Render a group-level summary only

Goal: Show only the group hierarchy without individual version entries.

Visualize with truncation per group

Goal: Limit the number of versions shown per group to avoid overwhelming output.

Write visualization to a buffer

Goal: Capture the tree output as a string for further processing.

Read versions from a file and visualize

Goal: Load versions from a text file and render the tree.

API Reference

SDK Functions

// Detailed tree: individual versions grouped by major version
func VisualizeVersions(versions []*Version, w io.Writer, maxItems int)

// Summary tree: group-level hierarchy only (no individual versions)
func VisualizeVersionGroups(versions []*Version, w io.Writer)

• maxItems = 0 means show all versions per group (no truncation)
• Both functions accept any io.Writer — os.Stdout, bytes.Buffer, or os.File
• Release time is only shown when PublicTime is non-zero
• Output uses Unicode box-drawing characters (├──, └──, ┌─)
• Labels are in Chinese: "版本总数" (total), "版本组" (group), "发布时间" (release time)

Output structure for VisualizeVersions:

版本总数: 8
版本组数: 2

┌─ 版本组: 1 (3个版本)
├── 1.0.0 (发布时间: 2024-01-01)
├── 1.0.1 (发布时间: 2024-02-01)
└── ...还有1个版本未显示

Output structure for VisualizeVersionGroups:

版本总数: 8
版本组数: 5

├─ 1 (3个版本组, 共3个版本)
│  ├─ 1.0 (1个版本)
│  └─ 1.1 (2个版本)
└─ 2 (3个版本组, 共3个版本)

CLI Commands

versions visualize [versions...]              # render tree from positional args
versions visualize --max-items <n> [v...]     # truncate to n per group
versions visualize --groups [v...]            # group-level summary only
versions visualize --from-file <path>         # read versions from file
versions visualize --groups --from-file <path> # combine flags

MCP Tools

Cross-References

• [[version-file-operations]] — read version lists from files before visualizing
• [[version-grouping]] — Group() is what powers the tree structure
• [[version-sorting]] — sort versions before visualization for predictable output

Important Notes

• Output uses Unicode box-drawing characters (├──, └──, ┌─) — ensure terminal supports UTF-8.
• Release time is only shown when PublicTime is non-zero (set it before calling VisualizeVersions).
• maxItems = 0 means show all versions per group with no truncation.
• Output labels are in Chinese ("版本总数" = total versions, "版本组" = version group, "发布时间" = release time).
• Both SDK functions accept any io.Writer — use os.Stdout, bytes.Buffer, or os.File.
• MCP response includes both visualization (the tree string) and total_versions / total_groups counts.