Work offline

All tutorials · Client workflow reference

You will edit a tracked file without a server connection, reconnect, acquire its required lock, and submit the result. Offline editing preserves local work but cannot reserve a file against other users. For a planned disconnect, acquiring locks beforehand gives stronger protection.

The walkthrough continues 1. Minimal server, before adding authentication. It uses that tutorial's game repository and Alice/Bob working copies. Run deployment commands from scribe-demo; parentheses below change into a working copy and return automatically. Use matching client/server binaries that support edit --offline and reconcile.

For an existing team workspace, use your own tracked file and configured endpoint instead. Skip the demo policy and server shutdown steps; leave shared services running. Files must already be downloaded. Creating a workspace, fetching missing content, acquiring locks, and submitting require a server connection.

1. Prepare the demo while connected

If you finished the minimal-server tutorial, start storage A again:

scribe-ctl --config scribe-cluster.toml up

Then make the demo hero require a lock and sync Bob's copy:

(
  cd work/alice-plain
  mkdir -p .scribe
  printf 'version = 1\n[locks]\nrules = ["Assets/Hero.txt"]\n' > .scribe/config.toml
  scribe add .scribe/config.toml
  scribe submit -m "Require a lock for the demo hero"
)
(
  cd work/bob-plain
  scribe sync
  scribe lock rules Assets/Hero.txt
)

Check that the rule query reports a required lock. This creates the policy in the fresh demo; do not overwrite an existing team's .scribe/config.toml. In an authenticated repository, activating main-branch policy changes requires Maintainer permission. The accepted policy on main governs every branch.

2. Disconnect and edit locally

Stop only this local demo server:

scribe-ctl --config scribe-cluster.toml down

Now open and edit Bob's local file:

(
  cd work/bob-plain
  scribe edit --offline Assets/Hero.txt
  printf 'hero mesh edited offline\n' > Assets/Hero.txt
  scribe status
)

Check that status reports the file as modified and pending reconciliation. edit --offline records the intent before making a read-only file writable. It makes no connection and acquires no lock. Ordinary edit would fail while the server is unavailable; it never silently switches to offline mode.

You can keep editing opened files and run local status or scan --verify. Local add --offline, delete, and move are also available, subject to their normal workspace protections. A plain add records the file too, but first tries the server to lock it and reports the check as skipped. An unknown submit outcome must be resolved online before starting new local operations; keep its pending state intact.

3. Reconnect and reconcile

Start the same server again with scribe-ctl --config scribe-cluster.toml up. In Bob's workspace, reconcile the local work:

(
  cd work/bob-plain
  scribe reconcile
  scribe status
)

In this demo, reconciliation reports the hero as ready and its pending marker clears. It checked the workspace branch's server revision and acquired the lock required by the current main policy. Your edited bytes and local base remain unchanged.

If a connection fails during reconciliation, retry the command. Successfully acquired locks stay held, even if their replies were lost; retrying an acquisition still owned by this workspace is safe. Inspect scribe lock list when you need to see what is held. Readiness is a check at the reported revisions, not a guarantee against later policy changes, new revisions, or administrative lock revocation.

4. Submit and verify from Alice's copy

(
  cd work/bob-plain
  scribe submit -m "Update hero after offline work"
  scribe lock release Assets/Hero.txt
)
(
  cd work/alice-plain
  scribe sync
  cat Assets/Hero.txt
  scribe log Assets/Hero.txt
)

Alice's file should contain hero mesh edited offline, and its history should include Bob's new change. Submit independently enforces current revisions and lock ownership. Locks survive successful submissions, so Bob explicitly releases the hero after finishing. If submit reports an unknown outcome, rerun submit to resolve it before continuing.

When someone else changed or locked the file

On a shared server, reconciliation can report several blockers for one file. A blocked run exits 1 and keeps local content. Unrelated ready paths can still complete reconciliation; acquired locks remain held.

• Locked: coordinate with the holder and retry after they release the lock. Offline editing grants no right to take another workspace's lock.
• Server changed: run scribe resolve --update, then scribe resolve to inspect the remaining conflicts. Review automatic text merges; binary assets may need an external editor or an explicit ours/theirs choice.
• Missing or reappeared file: restore a missing edit, or explicitly record the intended deletion. Preserve a reappeared file before deciding what to delete.

After editing an unresolved hero to the desired result, record the choice and check again:

scribe resolve --working Assets/Hero.txt
scribe reconcile
scribe submit -m "Resolve offline hero changes"

Run those commands inside the affected workspace, after starting resolution with resolve --update. If a pending move's source advanced, abort dependent moves in reverse order, resolve the source, and repeat the move. Automatic updating of pending move sources is not supported.

For a grouped merge rejected because the target advanced, abort and restart the merge instead of using resolve --update. Retain and reapply recovered manual edits as needed. See rename-aware merging.

Collect changes made outside Scribe

If an editor changed a tracked file before you opened it, first inspect locally, then collect tracked edits when connected:

scribe scan --verify
scribe reconcile --scan

Run these inside your workspace. --scan hashes tracked contents, opens discovered modified tracked files, and reconciles them. This can take time on a large project. It reports untracked and missing files separately: use explicit add, delete, and move to express those intentions. It never guesses a rename or turns every missing file into a deletion. Exit 0 means all opened paths passed; separately reported untracked or missing discoveries may still need your attention.

Prepare for your next offline session

While connected, sync the files you will need and open required assets normally:

scribe sync
scribe edit Assets/Hero.txt

The normal edit acquires a required lock before opening the file. Keep that lock while disconnected; already-opened files remain editable offline. For an optional path that you also want to reserve, run scribe lock acquire Assets/Hero.txt explicitly before editing. When back online, reconcile, submit, and release locks you no longer need.

See the offline workflow reference for exact state and retry behavior, and JSON output for scripting reconciliation reports.