Merge overlays across file renames

Use mergeOverlayCaptures when two workspaces start from the same snapshot and edits need to follow a renamed file. This guide uses Bun. Install core and Bun Crypto as described in Build and transport filesystem snapshots.

Carry an edit to the new path

Create both overlays from one base. Rename the file in one overlay and edit it at its original path in the other. Capture each overlay after its work finishes, then merge the captures against the base.

import * as BunCrypto from "@effect/platform-bun/BunCrypto"
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
 
const encoder = new TextEncoder()
 
const program = Effect.gen(function* () {
	const volume = yield* Vfs.fromFixture({
		entries: [{ kind: "file", path: "/draft.md", bytes: encoder.encode("Draft") }]
	})
	const base = yield* volume.snapshot
	const left = yield* Vfs.makeOverlay(base)
	const right = yield* Vfs.makeOverlay(base)
 
	const leftFs = yield* left.caller()
	yield* leftFs.rename("/draft.md", "/release.md")
 
	const rightFs = yield* right.caller()
	yield* rightFs.writeFile("/draft.md", encoder.encode("QA approved"), {
		access: "write",
		truncate: true
	})
 
	const ours = yield* Vfs.captureOverlayForMerge(left)
	const theirs = yield* Vfs.captureOverlayForMerge(right)
	const result = yield* Vfs.mergeOverlayCaptures(base, ours, theirs)
 
	if (result.conflicts.length > 0) throw new Error("Resolve conflicts before handoff.")
 
	const snapshot = yield* Vfs.applySnapshotDelta(base, result.delta)
	const merged = yield* Vfs.fromSnapshot(snapshot)
	const reader = yield* merged.caller()
 
	return new TextDecoder().decode(yield* reader.readFile("/release.md"))
})
 
console.log(await Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))))

The program prints QA approved. The merged snapshot contains /release.md in place of /draft.md. Both overlays and the base remain available for inspection.

Resolve competing destinations

If both overlays rename /draft.md to different paths, the merge returns one conflict for all three paths. Inspect the conflict's affectedPaths and the destinations in detail.ours and detail.theirs when its kind is rename. The preview delta keeps the affected paths at their base state and includes unrelated changes.

To take the left overlay's version, pass the conflict key back with take: "ours". Use the same base and ordered pair of captures on every retry.

const resolve = Effect.gen(function* () {
	const resolved = yield* Vfs.mergeOverlayCaptures(base, ours, theirs, {
		resolutions: [{ key: conflict.key, take: "ours" }]
	})
 
	if (resolved.conflicts.length === 0) {
		return yield* Vfs.applySnapshotDelta(base, resolved.delta)
	}
 
	return resolved
})

Choose theirs for the right overlay's version or base to keep the original. Each choice covers the paths and contents for the whole conflict group. Include all earlier choices when you resolve another group.

Keep the captures for the review

Keep the captures in the process that issued them. Later overlay writes leave the captured state intact, but taking a fresh capture or swapping the two inputs invalidates the old conflict keys.

Use a single-link regular file and a destination absent from the base for a supported move. If the merge fails with BaseMismatch, supply the snapshot both overlays started from. If it fails with LimitExceeded, inspect the error's field and the snapshot delta limits.

See the merge API reference for the full signature.