Conflicts

A Sync Conflict is a divergence Bowline can't merge while preserving both sides' intent. Conflicts are normal and safe in Bowline: instead of picking a winner or writing markers into your files, Bowline keeps your live view stable and sets the conflicting material aside until you repair it. This page explains the model; the resolve a sync conflict guide walks through the steps.

When a conflict starts

Most divergent work merges automatically. A conflict starts only when an Automatic Merge can't prove a safe result.

• The same line changed differently on two sides.
• A file's shape makes a safe merge impossible.
• A structured text file would no longer parse after merging.
• A delete on one side races an edit on the other.

Everything else keeps merging automatically: edits to different files, edits to different regions of the same file, and safe edits carried across a rename with strong File Identity evidence.

Your live view stays stable

When a conflict opens, each affected machine keeps its Local Active View: the version it already had visible at the real project path. Your editor, build, and tools keep working against a stable file. Bowline does not overwrite it, and it does not write conflict markers into your source automatically.

Bowline preserves the other sides of the conflict in a Conflict Bundle, stored outside the live project path. The bundle keeps the base, local, remote, and resolution material together so a repair has everything it needs.

~/.local/state/bowline/conflicts/conflict_abc123/
  prompt.md
  base/
  local/
  remote/
  resolution/
  manifest.json

The bundle lives under the daemon state root, so the path is platform-specific. The example shows Linux; macOS uses ~/Library/Application Support/bowline.

Conflict spans keep the rest syncing

Bowline scopes a text conflict as narrowly as possible. A Conflict Span is the smallest unresolved region inside a text file that needs repair. Edits outside the spans can still merge automatically and advance the Workspace Head, so a single tricky function doesn't freeze the whole file.

Structured text

Config and manifest files are Structured Text: their merged output must still parse to be safe. Bowline applies Automatic Merge to Structured Text only when the result parses. If a merge would produce an invalid config, Bowline opens a conflict instead of shipping a broken file. Env files merge per key, so the same key changed on two sides is the unit of conflict, not the whole file.

Conflicts stay passive but visible

A conflict never steals your focus or auto-launches a repair. It stays passive and visible across every surface: the status icon and dropdown, the CLI, and the TUI. You decide when to repair it.

Repair produces a Resolution Overlay

When you repair a conflict, the result is a Resolution Overlay, a proposed fix that doesn't touch your live project until you accept it. Accepting creates a new Workspace Snapshot and advances the Workspace Head. Rejecting discards the proposal and leaves your Local Active View untouched.

Bowline can hand the repair to an installed coding agent (it detects codex, claude, and cursor on your PATH) and always offers a copy-prompt fallback. Bowline instructs the agent to work only inside the resolution directory, respect Conflict Spans and per-key env merges, and avoid any source-control actions.

Next steps

• Resolve a sync conflict: the step-by-step repair flow.
• Workspace model: snapshots, heads, and automatic merge.
• Status and health: how conflicts surface in status.