Daily work with a game and a shared engine

This walkthrough uses a fictional project, Orbit, to show when ordinary workspace commands are enough and when scribe project helps. The same workflow applies to an application with a shared library or a product with separately versioned content.

Assume your team has already submitted the mounts and profiles configuration example in orbit-game, using real repository IDs, branch IDs, and accepted pins. You have configured your Scribe connection and logged in. Reading requires access to each selected repository; publication also requires permission to submit in the participating repositories.

The logical layout is:

orbit/                          parent workspace: orbit-game
  .scribe/_state/               parent local state
  .scribe/config.toml           parent file: pins and profiles
  game/
    src/foo.cpp                 ordinary parent file
  engine/                       mounted shared-engine repository
    .scribe/_state/             child's own local state
    src/collision.cpp           child file
  art-source/                   optional mounted art repository

game/ is an ordinary directory in the parent. engine/ and art-source/ are independent repositories because the configuration declares them as mounts. The parent owns each declaration and pin, while the child owns its files and history.

Create a working copy from a directory outside another Scribe workspace:

scribe workspace create orbit-game ./orbit --profile programmer
cd orbit
scribe project sync
scribe project status --scan --remote

The example programmer profile includes the game and engine, plus the root configuration automatically. It leaves the art repository unselected and does not download it. Continue only after sync completes.

Each case below starts at orbit/ with no pending workflows or unrelated opened changes. File edits and build/test steps use your usual editor and project tools. The shown cd, comment, and Scribe command syntax works in a Unix shell or PowerShell. Revision numbers are examples; use accepted revisions from your repositories. Ordinary submit includes all opened files in its workspace by default; project publish includes opened work in the parent and every selected child.

Case 1: change only a game file

You are fixing gameplay code in game/src/foo.cpp and do not need an engine change. Use the existing single-repository workflow:

scribe edit game/src/foo.cpp
# Edit game/src/foo.cpp, then build and test the game.
scribe status
scribe submit -m "Fix the game's collision response"

This submits a change to orbit-game. It does not submit to the engine or alter its pin. You could do this before project orchestration existed. scribe status shows the parent workspace; scribe project status additionally inspects mounted workspaces.

Case 2: change the engine and its game caller together

Suppose collision handling needs a new engine API and an update to the game code that calls it. Open each file in the workspace that owns it:

cd engine
scribe edit src/collision.cpp
# Implement the engine API change.
cd ..
scribe edit game/src/foo.cpp
# Update the caller; build and test the assembled game and engine.
scribe project status --scan --remote
scribe project publish -m "Update collision handling and its game caller"

Publication submits the engine change first. If the server accepts it as engine revision 43, Scribe stages revision = "43" for mounts.engine in the parent's configuration. It then submits that pin together with the opened game change. A teammate syncing the resulting parent revision receives the recorded engine revision, even if the engine branch later advances.

Before this command existed, you could perform the same work by submitting inside engine/, editing the parent's pin yourself, and submitting the parent. The new command coordinates those steps and persists their recovery state. It does not turn separate repositories into a single atomic transaction.

Case 3: adopt an engine improvement that is already published

Another developer has submitted an engine fix at revision 57. You want to test it in the game before updating the shared parent pin:

cd engine
scribe sync --revision 57
cd ..
# Build and test the game with engine revision 57.
scribe project update engine
scribe status
# Review the engine pin in .scribe/config.toml using your editor.
scribe submit -m "Adopt engine revision 57"
scribe project sync

project update engine takes the child's local sync/submission revision, so it stages 57 even if the engine's remote head is now 60. It does not submit the configuration or create another engine change. Stage and submit the pin before starting a parent sync against the old pin.

When you already know the desired accepted revision, you can instead stage it directly with scribe project update engine --revision 57, submit the parent, and run scribe project sync to materialize it. The command still checks access to the target; it does not bypass child permissions.

The argument engine is the configuration's mount name. A declaration named runtime with path = 'engine' would use scribe project update runtime.

Case 4: work without a large art-source checkout

A programmer needs source code and the engine, while an artist needs the source assets too. A repository mount keeps art history and permissions separate; a profile chooses whether a particular workspace uses that mount.

In an existing parent workspace, select the configured programmer profile:

scribe workspace view set --profile programmer
scribe project status --scan --remote

Project sync and publication skip the unselected art repository. They require no art access, do not fetch its content, and publication leaves its declared pin unchanged. If art was previously downloaded, deselection retains its child directory and local work; it is not a disk-cleanup command.

If you have art access and temporarily need one character's source files, include just that part of the mount, then remove the inclusion when finished:

scribe workspace view add art-source/Characters/Hero
# Work with the selected character assets.
scribe workspace view remove art-source/Characters/Hero

View changes sync automatically. Finish or preserve opened/local work before shrinking a selected child's view. If the art mount is selected but inaccessible, overall project sync is incomplete even when accessible game and engine files finish. The parent's own files still finish and its watermark still advances, so ordinary parent work is not blocked; the mount is retried by the next scribe sync. Grant access and retry, or explicitly exclude the mount. Parent access never grants art access.

Case 5: recover after the engine submits but publication stops

You run the publication from case 2. The engine is accepted, but the connection drops before the parent submission is confirmed. At the project root:

scribe project status --scan
scribe project publish --continue

The saved journal identifies the original engine and parent operations. Recovery resolves their outcomes and retransmits the same candidate only if necessary. It does not create another engine submission, and the parent pin uses the confirmed accepted child revision. The original prepared file contents and message remain the publication intent.

If the parent was definitively rejected—for example, another author changed the same game file—repeating the rejected operation cannot fix that conflict. Run scribe project publish --abort, resolve the parent's rejection using the ordinary conflict workflow, review the staged engine pin, then start a new publication. The already accepted engine change remains in its repository.

Abort preserves accepted history and local work; it does not roll back the engine. If a transmitted operation still has an unknown outcome, abort refuses: restore connectivity/access and use --continue to resolve that outcome first. See publication recovery for edits made during a pause and repository-restore handling.

Case 6: bring in one engine fix, then publish the game pin

Suppose the mounted engine's development branch accepted an ordinary crash fix as change 61, alongside other unfinished work you do not want. Start with clean, synced parent and child workspaces. Keep the engine on the branch the parent mount declares; cherry-pick the fix into that branch:

cd engine
scribe cherry-pick 61 --from development
scribe resolve
scribe status
# Resolve any conflicts and run the engine/game checks before submitting.
scribe submit -m "Backport engine crash fix"
cd ..
scribe project publish -m "Adopt the engine crash fix"

The child submission completes the cherry-pick workflow and records its source. The parent publication adopts that already accepted child revision without submitting the child again. Parent game edits opened before publication can join the same parent commit. project publish cannot submit an active merge or cherry-pick workflow on your behalf.

This applies equally to an engine child with a partial view. Clean excluded engine files are integrated using their accepted content; out-of-view conflicts require explicit inclusion and restart. The optional art-source mount is a separate repository and remains unselected throughout. See cherry-pick for subsequent merge behavior and partial-view integration for recovery commands.

What teammates see in the web interface

After the parent submission succeeds, its history includes the config pin change and any game-file changes in that submission. The engine mount links to the recorded engine revision under the viewer's own permissions. Viewing an earlier parent revision shows that revision's earlier engine pin.

The web mount editor also lets an authorized user submit a parent pin change for an already accepted child revision. It does not submit local files from your computer. Local edits and pending publication journals are inspected through the CLI; the web interface displays accepted repository state.

For command options, see the project CLI reference. For detailed guarantees and local state, see project orchestration.