Use this page to translate familiar workflows into Scribe commands. The tables compare everyday use cases, not interchangeable commands. Perforce examples use the centralized P4 workflow; depot paths, client views, and stream setup depend on your team's configuration.
Concepts first
| Concept | Scribe | Git | Perforce (P4) |
|---|---|---|---|
| Accepted history | Authoritative server repository | Local commits; pushing shares them with a remote | Submitted changelists on the server |
| Local working copy | Workspace for one repository and branch | Working tree backed by a local repository | Client workspace mapping depot files to local paths |
| Select local content | Workspace view: included file/directory prefixes | Sparse checkout selects working-tree content | Client view or stream view controls mapped content |
| Shared selection preset | Named profile in .scribe/config.toml | No direct named-profile equivalent in sparse checkout | Client templates or stream configuration can share mappings; different semantics |
| Prepare a change | Open files with edit, add, delete, or move | Stage content in the index with git add and related commands | Open files in a pending changelist |
| Publish prepared work | submit publishes opened file changes together as one changeset | commit records locally; push publishes commits | submit publishes a changelist |
| Pinned dependency repository | Versioned repository mount | Submodule records a child commit | Stream imports can select depot content at a revision; not a separate Git-style repository |
| Coordinate dependencies | project commands manage parent and selected mounted workspaces | Submodule commands plus commits/pushes in child and parent | Depends on depot/stream layout and team tooling |
A Scribe workspace can contain the whole repository or a partial view. A profile is a named preset for that view. Applying a profile saves its resolved selection; later profile edits take effect only when explicitly reapplied. Views and profiles do not grant or restrict repository permissions.
Git's index saves staged content. Scribe records opened intent and prepares the
opened files' content when submitting; scribe add is for new files, not a Git-like
way to stage the latest edits to tracked files.
See the official Git tutorial, sparse-checkout reference, submodule guide, and P4 client reference for the corresponding models.
Everyday commands
Run Scribe file commands inside the workspace that owns the files. FILE, URL,
and other uppercase words below are placeholders. Commands separated by “then”
are separate steps.
| Use case | Scribe | Git | Perforce (P4) |
|---|---|---|---|
| Get a working copy | scribe workspace create Game ./Game, then inside it scribe sync | git clone URL Game | Configure p4 client, then p4 sync |
| Start editing a tracked file | scribe edit FILE, then edit | Edit directly; stage afterward with git add FILE | p4 edit FILE, then edit |
| Add a new file | scribe add FILE | git add FILE | p4 add FILE |
| Move a tracked file | scribe move OLD NEW | git mv OLD NEW | Open for edit if needed, then p4 move OLD NEW |
| Delete a tracked file | scribe delete FILE | git rm FILE | p4 delete FILE |
| Inspect pending work | scribe status | git status | p4 opened |
| Discover edits made outside the workflow | scribe status --scan (also scribe scan) | git status | p4 reconcile -n previews discovered changes |
| Prepare discovered tracked edits | scribe reconcile --scan; add/delete reported paths explicitly | git add FILE for intended changes | p4 reconcile opens discovered adds, edits, and deletes |
| Publish prepared work | scribe submit -m "Fix" | git commit -m "Fix", then git push | p4 submit -d "Fix" for the default changelist |
| Publish selected files | scribe submit -m "Fix" -- FILE1 FILE2 selects exact opened files | Stage intended content, then commit and push | Put intended files in a numbered changelist, then p4 submit -c NUMBER |
| Get newer accepted work | scribe sync | git pull --ff-only when the branch can fast-forward; divergence needs integration | p4 sync; opened files may require resolve |
| Undo an unsubmitted file edit | scribe revert FILE | For an unstaged edit: git restore FILE | p4 revert FILE |
| Inspect history | scribe log or scribe log FILE | git log or git log -- FILE | p4 changes or p4 filelog FILE |
| Explain ignore rules | scribe ignore explain FILE | git check-ignore -v FILE | p4 ignores -v FILE |
scribe status emphasizes opened work; use --scan to discover unopened changes.
Scribe's scan reports without opening files. reconcile --scan opens discovered
tracked edits, but does not automatically add untracked files or open missing files
for deletion. P4's mutating reconciliation covers those cases too; see
p4 reconcile.
scribe submit needs the server: there is no separate local commit and later push.
By default, all opened file changes in the workspace are published together as one changeset
in its repository, with one revision number and message. A changeset can contain
multiple file edits, additions, deletions, and moves; “one changeset” does not mean
one changed file. This is closest to
p4 submit.
To submit a subset, pass exact opened file paths after --; other work stays
opened. This selects files, not staged snapshots or individual hunks. Move groups
remain complete, and active integration/conflict workflows require a full submit.
See submit options for selection and retry rules.
scribe revert restores workspace-base content and preserves the replaced
tracked content in .scribe/_state/recovery, modified or not. It does not create an inverse history commit like
git revert. Do not assume Git or P4 discard commands provide Scribe's recovery
behavior.
Branches, selections, and locks
| Use case | Scribe | Git | Perforce (P4) |
|---|---|---|---|
| Create a branch | scribe branch create feature | git branch feature | Create/populate a stream or branch files according to depot layout |
| Switch branches | scribe switch feature | git switch feature | Switch/configure the client stream and sync |
| Merge into the current branch | scribe merge feature, resolve, then submit | git merge feature, resolve if needed, then complete the commit and push | Integrate/merge source to target, p4 resolve, then p4 submit |
| Apply one source change | scribe cherry-pick CHANGE --from feature, resolve, then submit | git cherry-pick COMMIT, then push | Integrate the selected source revision range, resolve, then submit |
| Select source folders locally | scribe workspace view set --view Source --view Config | git sparse-checkout set Source Config | Edit the client/stream view, then sync |
| Apply a shared view preset | scribe workspace view set --profile programmer | No direct equivalent | Use your team's client/stream configuration |
| Include the entire repository | scribe workspace view set --all | git sparse-checkout disable | Map the required depot paths and sync |
| Reserve a file for exclusive work | scribe lock acquire FILE; required locks are also acquired by edit | No core Git file-lock command | Exclusive-open file type +l; p4 lock separately prevents other submissions |
Scribe switching requires no opened files, pending submit, or held locks. Scribe
has no branch deletion, rebase, or history rewrite. Its locks span branches within
the repository. P4's lock has different semantics: see the
P4 lock reference.
For P4 branch integration, see
p4 integrate.
Scribe view changes reconcile immediately and preserve displaced tracked files in recovery, so shrinking an existing view may not immediately free disk space. Selecting a view before the initial sync avoids downloading excluded content. Git sparse checkout controls the working tree; reducing transferred repository objects is a separate partial-clone concern.
Example: Game needs a new Engine feature
Assume Game declares a mount named engine at Engine, and both workspaces are
already synced:
Game/ Game repository workspace
├── .scribe/config.toml Records the Engine revision pin
├── Source/Game.cpp Owned by Game
└── Engine/ Engine repository workspace
└── Source/Engine.cpp Owned by EngineOpen the files in their owning workspaces, then edit them:
cd Game
scribe edit Source/Game.cpp
cd Engine
scribe edit Source/Engine.cpp
# Edit both files in your editor.
cd ..
scribe project status --scan
scribe project publish -m "Add Engine support and use it in Game"| Action | Scribe | Git with an Engine submodule | Perforce (P4) |
|---|---|---|---|
| Publish Engine work | Project publication submits the Engine workspace | Commit and push inside Engine | Submit the Engine files/changelist |
| Record the dependency | Publication updates Game's Engine pin | Stage the changed Engine submodule pointer in Game | Update the dependency pin/import configuration if your layout uses one |
| Publish Game work | Publication submits Game changes and the pin together | Commit and push Game changes with the pointer | Submit Game changes; composition depends on stream/depot setup |
| Retrieve the matching combination | scribe project sync (ordinary parent scribe sync also handles mounts) | Update Game, then git submodule update --init --recursive | Sync the configured client/stream and pinned imports |
In Scribe this creates separate accepted changesets in Engine and Game. Acceptance
is atomic per repository. If Game's submission fails after Engine succeeds, the
Engine change remains accepted; scribe project publish --continue resumes the
saved publication when the interruption can be retried. A rejected submission
may require aborting the publication, resolving the rejection, and publishing again.
You can perform the same work manually: submit inside Engine, return to Game,
run scribe project update engine, and submit Game. Running ordinary scribe submit
from Game only submits Game's opened files; it does not collect Engine's edits.
Submitting inside Engine does not itself advance Game's pin. Project publication
coordinates these steps and records progress for recovery.
P4 can map Game and Engine depot paths into one client and submit them together when the server and workspace layout allow it. That differs from Scribe's separate repository mount model; a P4 directory is not necessarily a repository boundary. Stream import and specification behavior is documented in the P4 stream reference.
Continue learning
- Client workflows: editing, submitting, recovery, and locks.
- Workspace views and profiles: partial working copies and shared presets.
- Game and Engine walkthrough: a complete mounted-project workflow.
- Project workflows: pins, publication, and interruption recovery.
- Client CLI reference: every command and option.