# Sync and continuity (/docs/concepts/sync-and-continuity)



Bowline keeps your work safe with near-continuous snapshots, not last-writer-wins
file copying. It records local writes, coalesces noisy file events, syncs
source-like state eagerly, and preserves both sides when offline work diverges.
This page explains what that means for your day-to-day work.

## Continuity, not file sync [#continuity-not-file-sync]

Consumer file sync tools treat the newest write as the truth and overwrite the
rest. That's fine for photos and documents. It's dangerous for code, where two
machines can each hold work you don't want to lose.

Bowline instead advances a project through
[Workspace Snapshots](/docs/concepts/workspace-model). As you work, your writes
collect in a Machine Overlay and become a new snapshot when they're safe to
merge. When two sides diverge in a way Bowline can't merge safely, it preserves
both rather than picking a winner. The result is continuity: your in-progress
work follows you, and nothing is silently overwritten.

## What syncs [#what-syncs]

The accepted workspace root, normally `~/Code`, is the sync boundary. Inside it,
Bowline syncs source-like state and skips dev junk. Repo, package, and
monorepo boundaries don't limit what syncs; the workspace root does.

| Category            | Syncs by default? | Examples                                        |
| ------------------- | ----------------- | ----------------------------------------------- |
| Source-like work    | Yes               | Source files, configs, notes, fixtures, repros. |
| Env files           | Yes               | `.env`, `.env.local`, `.env.*` under the root.  |
| Opaque Git state    | Yes               | `.git/` bytes, synced as encrypted state.       |
| Generated output    | No                | Build output, compiled artifacts.               |
| Dependencies        | No                | `node_modules`, vendored packages.              |
| Caches              | No                | Tool and package-manager caches.                |
| Explicit local-only | No                | Paths you mark local-only via path policy.      |

Ignore rules are evidence for how Bowline classifies a path, not the final
authority. Git-ignored but source-like state (env files, local notes, repros, and
fixtures) can still sync when it isn't generated, a dependency, a cache, or
explicitly local-only. You shape this with
[path policy](/docs/concepts/path-policy).

## Hydration: structure first, bytes on touch [#hydration-structure-first-bytes-on-touch]

On a fresh device, you see the whole `~/Code` tree before every byte is local.
Bowline shows the structure immediately and hydrates a project's contents the
moment you touch it. Once a project is hot, it behaves like an ordinary local
directory through aggressive local caching.

This is why a new machine is useful right away: you can navigate, search, and
open projects without waiting for a full download, and the bytes you actually use
arrive on demand.

## Working offline [#working-offline]

When you work offline, your writes still collect locally as a Machine Overlay.
When the machine reconnects, Bowline advances the Workspace Head with any changes
that merge safely. If your offline work diverges from newer work elsewhere,
Bowline opens a [Sync Conflict](/docs/concepts/conflicts) and preserves both
sides instead of overwriting either.

<Callout type="info">
  You don't run a sync command. The daemon records writes, coalesces noisy file
  events, and advances snapshots in the background. Use
  [`bowline status`](/docs/cli/commands) to see sync, hydration, and freshness
  state at any time.
</Callout>

## Inspecting sync state [#inspecting-sync-state]

Bowline makes sync observable rather than mysterious. Every meaningful
transition is an event, and status reads from those events.

* `bowline status` reports sync state, hydration, freshness, and safe next
  actions for the current project. Add `--watch` to stream changes.
* `bowline events` lists recent workspace events.
* `bowline explain <path>` explains why a path syncs, hydrates, stays local, or
  needs review.

## Next steps [#next-steps]

* [Conflicts](/docs/concepts/conflicts): how Bowline preserves and repairs
  divergent work.
* [Path policy](/docs/concepts/path-policy): control what syncs with
  `.bowlineignore`.
* [Status and health](/docs/concepts/status-and-health): read workspace and
  project state.
* [Architecture](/docs/concepts/architecture): the daemon, control plane, and
  byte plane underneath.