StructuredMerge Go

StructuredMerge Go provides Go packages for building merge-aware tools that need portable structured-merge contracts without leaving the Go runtime.

The module includes the core AST/review contracts, parser substrate support, format-specific merge libraries, binary/ZIP planning helpers, provider adapters, and a Go packaging recipe library.

Project links:

• Website: https://structuredmerge.org
• Implementations: https://structuredmerge.org/implementations.html
• Specification: https://github.com/structuredmerge/structuredmerge-spec
• Shared fixtures: https://github.com/structuredmerge/structuredmerge-fixtures

Behavioral Authority

The mature Ruby implementation is the StructuredMerge behavioral golden master. This Go implementation is a conformance consumer and currently lags Ruby in behavior and defect fixes. Shared specifications and fixtures are portable evidence admitted from reviewed Ruby behavior; historical Go behavior does not override Ruby when they disagree.

Names containing parity describe only the dimensions asserted by their cited fixtures. They do not claim complete behavioral equivalence with Ruby unless a versioned conformance profile explicitly says so.

Package Family

StructuredMerge Go is a layered package family. The lower layers provide parser, range, AST, merge, and template contracts; format packages apply those contracts to specific languages and data formats; provider packages bind a format family to a parser or serializer; workflow packages package Go module maintenance and Git-driver behavior.

Package README files in other implementations link to their root package-family guide. The Go implementation uses this root inventory because its packages live inside one module.

The family is intentionally layered:

• treehaver provides parser portability, backend discovery, byte ranges, and runtime capability reporting.
• astmerge provides the cross-format merge substrate: shared contracts, diagnostics, review state, and execution reports.
• Family packages such as markdownmerge, yamlmerge, and tomlmerge own parser-neutral behavior for one format family.
• Provider packages such as goldmarkmerge, goccygoyamlmerge, and pigeontomlmerge bind those families to concrete Go parser libraries.

Package	Layer	What it provides
treehaver	Parser substrate	Parser backend registry, byte ranges, node wrappers, source locations, and binary tree contracts.
astmerge	Merge substrate	AST merge contracts, diagnostics, planning, review, replay, and nested merge vocabulary.
asttemplate	Template substrate	Template/session transport contracts.
astcrispr	Structured edits	AST edit recipes for generated blocks and template-owned regions.
astmergegit	Git integration	Merge-driver, diff-driver, conflict inspection, and language registry plumbing for smorg-go.
plainmerge	Text	Plain-text fallback contracts.
jsonmerge	JSON and JSONC	Object/array-aware JSON merge behavior using tree-sitter-language-pack where selected.
yamlmerge	YAML	YAML-family merge contracts.
tomlmerge	TOML	TOML-family merge contracts.
markdownmerge	Markdown	Markdown-family merge contracts.
rubymerge	Ruby source	Ruby source merge contracts.
gomerge	Go source	Go source merge contracts.
rustmerge	Rust source	Rust source merge contracts.
typescriptmerge	TypeScript source	TypeScript source merge contracts.
binarymerge	Binary	Binary tree planning contracts.
zipmerge	Archives	ZIP archive planning helpers.
goccygoyamlmerge	YAML provider	Uses goccy/go-yaml as the YAML parser/emitter provider path.
pigeontomlmerge	TOML provider	Uses Pigeon generated parser code as the TOML provider path.
goldmarkmerge	Markdown provider	Uses Goldmark as the Markdown parser provider path.
goparsermerge	Go provider	Uses the Go standard library go/parser provider path.
godstmerge	Go provider	Uses go-dst for decorator-preserving Go source edit projection.
kettlegomodder	Recipe tooling	Go module maintenance and package recipe helpers.

Install

go get github.com/structuredmerge/structuredmerge-go

Import only the packages your tool needs:

import (
	"github.com/structuredmerge/structuredmerge-go/astmerge"
	"github.com/structuredmerge/structuredmerge-go/jsonmerge"
)

Command

The Go implementation ships the implementation-specific smorg-go command. Use that name in git configuration unless a package manager or local install has provided a smorg symlink.

Package-manager formulas may expose the selected implementation as smorg. For a local user-created symlink:

ln -s "$(command -v smorg-go)" ~/.local/bin/smorg

git config merge.smorg-go.driver 'smorg-go merge-driver %O %A %B %P'
git config diff.smorg-go.command 'smorg-go diff-driver'
smorg-go conflicts diff path/to/file-with-conflicts.go
smorg-go languages --gitattributes

merge-driver updates Git's %A file by default, or writes to --output when used outside git. diff-driver accepts both the two-argument local form and the seven- or nine-argument forms Git passes to external diff commands. conflicts diff reports conflict-marker regions in a file that already contains Git conflict markers.

Semantic merge-driver coverage is fixture-backed for JSON and for the first Go source-language slice. Other language and format paths are git-compatible command surfaces without semantic driver coverage.

Packages

Core:

• treehaver - parser substrate, byte ranges, backend adapters, and binary tree contracts.
• astmerge - AST merge contracts, diagnostics, planning, review, replay, and nested-merge vocabulary.
• asttemplate - template/session transport contracts.

Format libraries:

• plainmerge
• jsonmerge
• yamlmerge
• tomlmerge
• markdownmerge
• rubymerge
• gomerge
• rustmerge
• typescriptmerge
• binarymerge
• zipmerge

Provider and recipe libraries:

• goccygoyamlmerge
• pigeontomlmerge
• goldmarkmerge
• goparsermerge
• kettlegomodder

Portability

The Go packages are developed against the shared StructuredMerge fixtures. Those fixtures encode portable behavior derived from the Ruby golden master and reviewed for cross-runtime use. Conformance checks live in package tests and in the shared spec/fixture tooling rather than in a static status document.

Development

Common checks:

• mise run check
• go test ./...

The tree-sitter backend path uses the sibling tree-sitter-language-pack checkout through a local replace in go.mod. Repo tasks build its ts-pack-core-ffi crate first and compile with the tspack_dev build tag.