Open Collective
Kettle-Dev
Contribute
Connect
About
鈽笍 toml-merge: Intelligently merge TOML by AST structure
Published on December 19, 2025 by Peter Boling

馃尰 Synopsis


toml-merge provides intelligent merging of TOML files by parsing them into
tree-sitter AST nodes and comparing structural elements. It supports:聽
  • Smart key matching - Keys and tables are matched by their structural signatures
  • Table matching - Tables are matched using a multi-factor scoring algorithm that considers
    key similarity, value overlap, and position
  • Freeze blocks - Mark sections with comments to preserve them during merges
  • Configurable merge strategies - Choose whether template or destination wins for conflicts,
    or use a Hash for per-node-type preferences with node_splitter (see [ast-merge][ast-merge] docs)
  • Full TOML support - Works with all TOML 1.0 features including inline tables, arrays of tables, and dotted keys

Thanks to tree_haver and ast-merge it works with any of these toml backends / parsers:
  1. tree-sitter-toml (tree-sitter based)
  2. toml gem (parslet based)
  3. toml-rb gem (citrus based)

Example


require "toml/merge"

template = <<~TOML
聽 [package]
聽 name = "my-app"
聽 version = "1.0.0"

聽 [dependencies]
聽 serde = "1.0"
TOML

destination = <<~TOML
聽 [package]
聽 name = "my-app"
聽 version = "2.0.0"
聽 authors = ["Custom Author"]

聽 [dev-dependencies]
聽 tokio = "1.0"
TOML

merger = Toml::Merge::SmartMerger.new(template, destination)
result = merger.merge

puts result.content if result.success?
# The [package] section is merged with destination's version and authors preserved,
# [dependencies] from template is included,
# [dev-dependencies] from destination is kept