vizb merge

Combine multiple benchmark JSON files into a single dataset. Supports tag-based deep merging for release tracking.

Usage

vizb merge [files/directories...] [flags]

Input Types

JSON files: one or more .json files generated by vizb -o file.json
Directories: scans for all .json files in the directory
Mix: combine files and directories in a single command

# Specific files
vizb merge run1.json run2.json -o merged.json

# Entire directory
vizb merge ./results/ -o all.json

# Mix files and directories
vizb merge ./old_results/ latest.json -o comparison.json

Flags

Flag	Short	Default	Description
`--output`	`-o`	(stdout)	Output file path (always JSON)
`--tag-axis`	`-A`	`n`	Where to inject tag: `n` (name), `x` (xAxis), `y` (yAxis)

Outer Merge (Untagged)

When merging benchmarks without tags, vizb concatenates all entries. Same-name benchmarks are deduplicated — first occurrence wins.

vizb bench-a.txt -o a.json -n "Sort"
vizb bench-b.txt -o b.json -n "Hash"
vizb merge a.json b.json -o combined.json

Result: both benchmark groups in one file.

Inner Merge (Tagged)

When benchmarks share the same name but have different tags, vizb deep-merges them:

# Tag individual runs
vizb bench-v1.txt -o v1.json --tag v1 -n "Sort"
vizb bench-v2.txt -o v2.json --tag v2 -n "Sort"

# Merge
vizb merge v1.json v2.json -o comparison.json

The merge process:

Deduplication — same name + tag → keep latest timestamp
Deep merge — different tags → single benchmark with chronological data
Legacy — untagged entries prepended before tagged data

Tag-Axis

Control which dimension receives the tag annotation:

# Inject tag into X-axis (versions on X-axis)
vizb merge v1.json v2.json -A x -o comparison.json

Value	Target
`n`	Name dimension (default)
`x`	X-axis — use for version comparison
`y`	Y-axis