Path policy

Path policy is how Bowline decides what under your workspace root follows you and what stays local. The default is workspace continuity: once you accept a root, every non-excluded file under it syncs as encrypted workspace state. You override the defaults with a .bowlineignore Path Policy File when a path needs to be excluded or explicitly included.

The sync boundary is your workspace root

The accepted workspace root, normally ~/Code, is the sync boundary. Everything portable under that root follows you to every authorized device.

Repo, package, and monorepo boundaries do not limit default sync. A folder with no Git remote, a nested package inside a monorepo, and a plain non-repo directory all follow the same rule: if it lives under the accepted root and isn't excluded, it syncs. You don't mark projects, register repos, or draw boundaries inside the root for Bowline to carry your work.

What syncs by default

Bowline classifies each path to carry it safely. Source and developer files sync; generated junk, dependencies, and caches stay local. This keeps node_modules off the wire while your real work travels.

For how Git state and .env files are handled in depth, see Git and source control and env sync.

Ignore files are evidence, not authority

Bowline reads .gitignore and similar ignore files as classification evidence, not as final sync authority. Being git-ignored tells Bowline a path is probably generated, but it doesn't decide that the path stays off your other machines.

Source-like state you keep out of Git still syncs. Local .env files, scratch notes, reproduction cases, and test fixtures are real work, so they follow you even when Git never sees them. A path stops syncing only when it's generated, a dependency, a cache, explicitly local-only, or blocked by safety or organization policy.

The .bowlineignore Path Policy File

The .bowlineignore Path Policy File records explicit include and exclude policy for its directory subtree. It syncs as ordinary workspace state, so the policy travels with the project. Patterns are relative to the file's own directory, so a file under ~/Code/acme/web/.bowlineignore matches paths within ~/Code/acme/web.

There are two kinds of pattern:

• Plain patterns exclude paths from workspace sync.
• ! patterns explicitly include paths and can override the built-in generated, dependency, and cache defaults.

This example excludes local-only paths and re-includes two paths Bowline would otherwise skip:

# Patterns are relative to this file's directory.

# Exclude local-only scratch work from sync.
scratch/
notes/local-only.md

# Re-include a generated file that is really source you hand-edit.
!src/generated/icons.ts

# Re-include a vendored dependency you want to travel with the project.
!vendor/patched-lib/**

Path policy precedence runs from strongest to weakest: a hard safety block or organization policy, then .bowlineignore, then the built-in high-confidence defaults, then sync everything else. An ! include can override the built-in defaults, but it can't override a hard safety block or organization policy. If a path looks like a secret or is blocked by your organization, an include won't force it onto the wire.

Including a previously excluded path

Adding an ! include for a path that wasn't syncing is a first import, handled conservatively. Bowline never resolves it with last-writer-wins.

1. If only one machine has the content, it syncs.
2. If multiple machines have identical content, it syncs.
3. If multiple machines have different local content, Bowline preserves every local copy and raises a Sync Conflict for you to resolve.

After the import succeeds or the conflict resolves, that path becomes ordinary workspace state and follows the normal rules for its file type. There's no permanent "imported" mode.

Excluding a previously synced path

Adding a plain exclude pattern for a path that was syncing changes future sync only. It's never a delete.

• New machines don't receive the path.
• Machines that already have it keep their local copy as unmanaged local state.
• Status reports that copy as excluded local state.

Cleanup is explicit. Bowline leaves existing local copies in place until you remove them yourself, so excluding a path can't lose work you still have on disk.

Inspecting why a path syncs

When you're unsure why a path is or isn't syncing, run bowline explain <path>. It reports the matched rule, the detected file type, the current classification, the storage mode, access flags, and the next safe actions, so you can see exactly which policy applied.

bowline explain ~/Code/acme/web/fixtures/demo.sqlite

Add --json for scriptable output, and see status and health for the broader picture across a workspace.

Next steps

• Git and source control: how .git/ syncs as Opaque Git State.
• Env sync: how .env files are imported, merged by key, and rematerialized.
• Conflicts: what happens when a first import diverges.
• Setup recipes: the .bowlinesetup file for preparing a fresh machine or agent.
• CLI commands: the full command reference, including bowline explain.