What's the difference between shallow and deep merge here?

Shallow merge is equivalent to spreading two parsed objects, {...a, ...b}: every top-level key from document B overwrites the same key from document A, even if both sides had a nested mapping there. Deep merge instead recurses into any key where both A and B have a plain mapping, combining their fields, rather than letting B's mapping replace A's outright.

How are sequences (arrays) handled in deep merge mode?

Wholesale replacement, not concatenation. If a key holds a sequence in both A and B, the merged result uses B's sequence exactly as it is; A's sequence at that key is discarded entirely. This intentionally mirrors this site's JSON Object Merger's deep-merge behavior, so the two tools stay consistent with each other.

Which document wins when both have a scalar at the same key?

B always wins for scalar conflicts, in both shallow and deep mode. Think of A as the base document and B as the overrides being layered on top, exactly the same mental model as the JSON Object Merger.

What happens if a key is a mapping in A but a sequence or scalar in B?

B's value wins outright. Deep merging only recurses when both sides agree the key holds a plain mapping; any type mismatch, a mapping in A vs. a sequence or scalar in B, is treated the same as any other scalar conflict, with B's version replacing A's.

Does this tool send my YAML anywhere?

No, both documents are parsed and merged entirely in your browser using the same yaml parser used across this category. Nothing you paste is uploaded.

Merge YAML Documents Online - Shallow & Deep Merge

Overview

Introduction

Layering an override document over a base config, an environment-specific values.yaml over a shared defaults file, or combining two partial YAML records into one, comes up constantly in config-driven systems like Helm or Kustomize, and doing the nested-merge logic correctly by hand is easy to get subtly wrong.

This tool merges two YAML documents for you, with a toggle between a simple shallow spread and a full recursive deep merge, deliberately mirroring this site's JSON Object Merger's exact semantics so the two behave identically regardless of which format your config happens to be in.

What Is YAML Merge Tool?

A merge tool that combines two YAML documents, A as the base and B as the overrides, into a single result, in either shallow or deep mode.

Shallow mode is exactly what {...a, ...b} would do to the parsed values; deep mode extends that by recursing into any key where both documents have a nested plain mapping, rather than letting B's mapping replace A's outright.

How YAML Merge Tool Works

Both documents are parsed and confirmed to be YAML mappings (not sequences or scalars) at the top level; a mismatch on either side is reported with which side failed. In shallow mode, the result is simply A's mapping spread with B's on top.

In deep mode, the tool walks B's keys one at a time: if the same key holds a plain mapping in both A and the merged-so-far result, it recurses into those two mappings and merges them the same way; otherwise B's value at that key replaces whatever was there, which is also what happens for sequences, since sequences are never treated as "plain mappings" for the recursion check.

When To Use YAML Merge Tool

Use it to layer environment-specific YAML config (staging vs. production values) on top of a shared base document.

Deep mode is the better fit whenever both documents have nested sections you want combined field-by-field rather than one nested section wholesale replacing the other.

Often used alongside YAML Sorter, YAML Formatter & Prettifier and YAML to Canonical Normalizer.

Features

Advantages

Offers both shallow (spread-equivalent) and deep (recursive) merge modes in one tool, matching the JSON Object Merger's exact behavior for consistency across formats.
Deep mode correctly recurses into arbitrarily nested shared mappings, not just one level.
Reports parse errors per side, so you know exactly which document to fix.
Runs entirely client-side, so configuration values never leave your browser.

Limitations

Deep mode never merges sequences element-by-element; a shared sequence key is always replaced wholesale by B's version.
Only merges exactly two documents; combining three or more config layers requires running the tool twice, feeding the first result back in as document A.

Examples

Shallow merge

Input

A: a: 1
nested:
  x: 1
B: nested:
  y: 2

Output

a: 1
nested:
  y: 2

B's nested mapping entirely replaces A's in shallow mode, so A's x key is lost.

Deep merge

Input

A: a: 1
nested:
  x: 1
B: nested:
  y: 2

Output

a: 1
nested:
  x: 1
  y: 2

In deep mode, the shared nested mapping is merged recursively, keeping both x and y.

Best Practices & Notes

Best Practices

Use deep mode whenever both documents have nested sections you expect combined, not replaced.
Remember sequences always replace wholesale in deep mode; if you need list items combined, merge that specific field with a dedicated array-merge step separately.
Treat document A as the base/defaults and document B as the overrides for the clearest mental model, since B always wins conflicts in both modes.

Developer Notes

The merge logic is a direct YAML-flavored port of this site's mergeJsonObjects: the same isPlainObject(aValue) && isPlainObject(bValue) recursion check (which explicitly excludes arrays), the same B-wins-on-conflict rule, and the same per-side error reporting shape, just parsing and re-serializing with the yaml package instead of JSON.parse/JSON.stringify.

YAML Merge Tool Use Cases

Layering environment-specific YAML config over a shared base document
Merging a user's custom YAML settings over application defaults
Combining two partial YAML records (e.g. from Helm values files) into one complete document

Common Mistakes

Expecting deep mode to merge sequences index-by-index, sequences are always replaced wholesale, never merged.
Using shallow mode when nested config sections need combining, shallow mode lets B's nested mapping silently replace all of A's fields at that key.

Tips

If you need to merge three or more YAML documents, run this tool repeatedly, feeding each result back in as document A for the next merge.
Run YAML Diff first if you want to see exactly what would change before committing to a merge.
Use YAML to Canonical Normalizer on the result if you need a consistent, diffable form for committing merged config to version control.

YAML Merge Tool