Working Offline (Pack & Go)

Most of the time your drive is a live view of the project: files stream on demand and saves sync in the background. But sometimes you need to work somewhere the network doesn't reach - a set visit, a flight, a site with no usable uplink. Swarmfile handles that, and there are two different things you can set up before you go:

Reading offline - download a scope so every file in it opens with no network.
Writing offline - reserve a scope so it stays editable with no network, and nobody else can change those files while you're gone. This is Pack & Go.

You can also just disconnect and keep working - saves queue durably and sync when you're back (see Casual offline below). Pack & Go is for when you want to be sure the files you need are readable and writable while you're away.

Casual offline (no preparation)#

If you only need the files you've already been working on, you don't have to do anything special.

Saves keep working. Every write returns immediately against a durable local queue, so a dropped connection doesn't block your application. The queue survives quitting or restarting Swarmfile and resumes when the network is back - see Reading the sync status.
Reads work for anything still in your cache. Files you've opened recently stay local until the cache trims itself, and reading a file you already have open keeps working through a brief outage.
Reads do not work for files you never downloaded. A file you haven't opened yet streams from the hub or a LAN peer, so with no network it isn't there.

The catch is collisions: if a teammate changes a file while you're editing it offline, Swarmfile catches it when your save lands and records a conflict rather than silently keeping both. Writes to that file are refused until you resolve it. Pack & Go avoids the surprise by telling everyone else the file is yours before you leave.

Download a scope for reading#

Use Make available offline when you want the content resident but aren't going to edit it.

One file or folder: in the Desktop App, open the row's menu and choose Make available offline.
The whole branch: in the Desktop App, open the ⋯ Project actions menu on the active project in the left rail and choose Download entire branch (keep offline).
From a terminal: swarmfile hydrate start [path], then swarmfile hydrate status to watch it.

While it downloads, the Desktop App shows progress and lets you cancel. When it finishes, the files are pinned against the cache's normal cleanup, so they stay put until you release them.

To undo it:

Stop keeping it offline: ⋯ Project actions (left rail) → Stop downloading / keeping the project offline, or swarmfile hydrate release [path]. This drops the offline mark; the content stays in the cache until the cache needs the space.
Give the disk space back now: Free up space on a file/folder row, Free up space (whole project)… under ⋯ Project actions in the left rail, or swarmfile hydrate free-space [path]. Unsynced changes are never touched - see Freeing up space.

Downloading for reading does not stop anyone else from writing to those files, and it does not reserve them for you. That's what Pack & Go adds.

Before you go: reserve a scope (Pack & Go)#

Pack & Go does two things at once: it downloads every file in the scope, and it reserves the whole scope with one long-lived offline reservation. The reservation is enforced by the hub, so while it's active nobody else can write those files - and you can keep writing them with no hub at all. The hub refuses a reservation that overlaps one another machine already holds, or that covers a file someone else is editing right now, and names who is in the way. Active reservations are visible in the Desktop App's Locks panel, with who holds them and when they expire.

In the Desktop App: open ⋯ Project actions on the active project in the left rail and choose Reserve entire branch for offline (Pack & Go)…. It shows the size before you confirm, lets you pick a reservation length (7, 14, or 30 days), and reports progress; if the scope is blocked, it tells you who holds it and reserves nothing.

From a terminal:

# Reserve a folder for a two-week trip: the lease is extended to cover it
swarmfile offline prepare ./Projects/shots/seqA --offline-days 14

# Check progress, resume one a restart interrupted, or release everything
swarmfile offline status
swarmfile offline resume
swarmfile offline return ./Projects/shots/seqA

Reserve only what you need rather than the whole project where you can - the locks you take are locks your teammates can't use, and a smaller scope means a faster prepare.

How long a reservation lasts#

The lease defaults to 7 days and can't exceed 30 days.
It is only renewed while you're online - at startup and every six hours after that. A reservation does not extend itself while you're disconnected, so pick a length that covers the whole trip.
If a lease lapses while you're still offline, the file is no longer exclusively yours: the engine warns you as the expiry approaches, and anyone else can claim the file once it does. Passing --offline-days (how long you expect to be away) extends the lease to cover the trip when it would otherwise lapse; --duration-secs sets an exact lease (up to 30 days) and, if you give an explicit one shorter than the trip, the command warns rather than overriding your choice.
A single prepare covers up to 100,000 files. A larger scope is refused with a message telling you to narrow it.
If a prepare is interrupted (a crash, a restart), swarmfile offline status names the interrupted scope and swarmfile offline resume completes it without re-reserving what you already hold. offline status also prints what this machine holds right now (file checkouts and folder/project reservations).
Switching a mount to another branch releases the reservation(s) that mount held on the branch you're leaving. A reservation protects one branch's paths, and after the switch the engine can neither renew nor release it, so Swarmfile hands it back instead of leaving your teammates blocked until it expires. If you'll still need offline work on the other branch, reserve there after switching. Switching the mount to another project or organization does the same for the reservations on the project you're leaving. Per-file checkouts are different: they stay yours, keep renewing on the project they were taken in (after a switch within the same organization), and survive quitting and restarting Swarmfile; after a switch to another organization they wait, and resume when you switch back.

Coming back#

Choose Return from offline (release reservations) under ⋯ Project actions in the left rail, or run swarmfile offline return with no path to release every reservation this machine holds. A path releases the reservations at or under that folder. Releasing doesn't delete any content - the files stay in your cache until it needs the space, and you can free them deliberately as above. If saves are still syncing, the release waits a few seconds for them and then tells you how many are still going; they land on their own, but until they do a teammate could take one of those files and force a conflict.

While you're offline#

Inside a reserved or downloaded scope:

Opening and reading files works from the local copy.
Saving works; saves queue locally and sync when you reconnect.
Creating files and folders works; the durable create queue lands them when the hub is reachable again.
Changelists (staged workgroups) keep working.

Anything that needs the hub doesn't: listing someone else's live presence, taking a new lock on a file, comparing history, comment threads, and merge requests all wait until you're back.

Any existing file on a mount you can write to can be edited offline, whether or not it's inside a reserved scope: the save is queued and reconciled when you're back. What a reservation buys you is the guarantee - nobody else can change those files while you're away, so your saves land cleanly. Outside a reservation you may get a conflict if a teammate changed the file first (see below); to be sure the files you need are covered, include their folder in the prepare.

Coming back and resolving conflicts#

When the network returns, queued saves land on their own. The Desktop App's header stays on Syncing N until the queue is empty - see Reading the sync status.

If someone changed a file you edited while you were away, you'll get a conflict instead of a silent overwrite. The file is read-only until it's resolved (a save fails with "permission denied", or "access denied" on Windows), and the Desktop App shows it in Branches & conflicts in the left rail. From the CLI:

swarmfile conflicts                     # list blocked files
swarmfile conflicts resolve <path> --auto          # three-way merge when possible
swarmfile conflicts resolve <path> --winner local  # or remote, or keep-both

--auto exits with code 2 when it can't merge cleanly, so a script can tell "a person must choose" apart from a real failure. See Branches & Merging for the conflict model, and the CLI reference for every conflicts flag.

For administrators#

Bulk Pack & Go can be turned off on a machine or fleet with the SWARMFILE_PACK_AND_GO_POLICY environment variable on the engine process (disabled refuses both bulk prepare and single-file checkout locks). An unrecognized value fails closed - a typo disables Pack & Go rather than allowing it - and the engine now says so at startup (and swarmfile-doctor reports it), so a typo surfaces immediately instead of when someone first tries to pack. On a managed deployment the service can additionally deliver an organization-wide Pack & Go policy to each engine; the stricter of the organization policy and the machine's environment variable applies. See Engine Config File.

Working with Files - saving, sync status, freeing up space, and locks.
CLI: swarmfile - hydrate, offline, fetch, and conflicts in full.
Engine Config File - SWARMFILE_PACK_AND_GO_POLICY and the streaming/cache settings.