# Conflicts (/docs/concepts/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](/docs/guides/resolving-conflicts) guide walks
through the steps.

## When a conflict starts [#when-a-conflict-starts]

Most divergent work merges automatically. A conflict starts only when an
[Automatic Merge](/docs/concepts/workspace-model) 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](#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](/docs/concepts/workspace-model) evidence.

## Your live view stays stable [#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.

```text title="Conflict bundle layout"
~/.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 [#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](/docs/concepts/workspace-model), so a single tricky function
doesn't freeze the whole file.

## Structured text [#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 [#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.

| Surface                     | What it shows                              |
| --------------------------- | ------------------------------------------ |
| `bowline status`            | Conflict count and the affected project.   |
| `bowline resolve`           | Per-conflict diffs and repair actions.     |
| TUI                         | Interactive review and repair.             |
| Menu Bar Status App (macOS) | Ambient conflict count and degraded state. |

## Repair produces a Resolution Overlay [#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.

<Callout type="warn" title="You hold the accept">
  A Resolution Overlay only becomes canonical state when you accept it. Until
  then, your live files stay exactly as they were.
</Callout>

## Next steps [#next-steps]

* [Resolve a sync conflict](/docs/guides/resolving-conflicts): the step-by-step
  repair flow.
* [Workspace model](/docs/concepts/workspace-model): snapshots, heads, and
  automatic merge.
* [Status and health](/docs/concepts/status-and-health): how conflicts surface
  in status.