kimo merge

.kimo files are laid out so that plain git merge is clean in the common case (spec §18). For the rest, kimo merge merges semantically: per node and per property, per variable (and per themed entry), per header member. It never drops a side silently. Disagreements it cannot settle are stored in the file as merge conflicts (spec §21), so the result is still valid JSON that validates, renders, and opens in Kimo with the Conflicts tab (board 18).

Set it up per repository (the desktop app's Settings › Git merge driver does exactly this):

git config merge.kimo.name "Kimo semantic merge"
git config merge.kimo.driver "kimo merge %O %A %B %P"
echo '*.kimo merge=kimo diff=kimo' >> .gitattributes

Git runs it as kimo merge <base=%O> <ours=%A> <theirs=%B> <path=%P>, and the result is written into %A.

• 0, clean. %A holds the canonical merged document.
• 1, conflicts stored. %A holds a valid document with a conflicts table and merge labels. Git marks the path as conflicted. Open it in Kimo, pick a side per row (or "Take all ours / theirs"), then Mark resolved & save, and commit.
• 2, not mergeable. An input is unparsable, invalid or uses a newer format. %A gets git's textual merge with ordinary conflict markers. The editor's failed-load banner explains them.

Options:

• -o <file> writes the result somewhere else and leaves <ours> untouched.
• -L <ours>,<base>,<theirs> gives display labels stored in merge (for example -L %X,%S,%Y on git versions that support those placeholders). The order is the same as git merge-file -L.
• --marker-size <n> sets the marker size of the textual fallback (%L).

Custom merge drivers only run where they are configured locally. GitHub and GitLab merges and CI checkouts ignore merge=kimo. You can also run kimo merge as a pre-merge step in CI.

The merge itself is mergeDocuments in @kimo/core-schema (src/merge/three-way.ts). The editor uses the same function when the file changes on disk while you have unsaved edits.