Workspace views and profiles

A workspace view selects repository-relative files and directories to materialize. It controls sync and which paths can be opened for ordinary edits or submitted from local files. Merge and cherry-pick still cover their complete source changes, including metadata-only decisions outside the view; see partial-view integration. A view is not an access control boundary. Repository permissions still apply to every remote operation. Ignore rules remain separate and never hide tracked changes.

Select paths in an existing workspace

scribe workspace view show
scribe workspace view set --view Source --view Config
scribe workspace view add Art/Characters
scribe workspace view remove Art/Characters
scribe workspace view set --all

set replaces the saved inclusion list. add extends it; remove removes a prefix and any selected descendants. A prefix matches that exact file or the files beneath that directory, with exact spelling. Duplicate and redundant child prefixes are collapsed. All prefixes obey Scribe's portable path rules.

Views are inclusion lists. If Art is selected, remove Art/Characters cannot express an exception: first replace Art with the specific subdirectories you want. Removing the last inclusion is refused, because an empty inclusion list means the entire repository. Use set --all explicitly for that selection.

Each change pins the current branch head and reconciles the new selection to that revision, including remote changes in retained paths. It preserves the workspace ID, branch, opened intent, and lock ownership. Excluded server trees are not enumerated or downloaded; exclusions are found from local baselines. Changing a view does not release locks.

Share named profiles

Add and submit a .scribe/config.toml file (create the .scribe/ directory first if it does not exist):

version = 1

[profiles.programmer]
include = ['Source', 'Config']

[profiles.artist]
include = ['Art', 'Config']

[profiles.build]
include = ['.']

Then select a profile when creating or updating a workspace:

scribe workspace create game ./work --profile programmer
cd work
scribe sync
scribe workspace profiles
scribe workspace view set --profile artist
scribe workspace view set --profile programmer --view Art/Characters
scribe workspace view remove Art/Characters

Creation records the selection; sync performs the initial download, as with ordinary workspace creation. view set/add/remove perform the transition immediately. With --profile, repeated --view options add local inclusions to the named profile. view add/remove also provide local overrides without editing the shared definition. Profile selections include .scribe/config.toml itself so it can be edited and submitted normally.

Definitions are read from accepted history at the current branch head (the saved target revision during an active merge or cherry-pick), even if .scribe/config.toml is outside the current view. Unsubmitted local edits do not redefine a profile. The chosen prefixes are saved as a snapshot: ordinary sync does not automatically apply subsequent profile edits. Reapply the profile explicitly to adopt a new definition and reset local overrides. Workspace info shows the originating profile name alongside the actual saved prefixes; a plain view set --view ... or --all clears that name.

Shared configuration format

Profiles use [profiles.NAME] tables with nonempty include arrays. . selects the whole repository; ordinary entries are canonical file or directory prefixes. The same .scribe/config.toml also contains [locks]. One shared parser validates both sections, including versions, unknown keys, and size limits. See the repository configuration specification for the full format and section-specific permissions. Profile-only changes on main require Writer permission; changing active lock-rule values requires a Maintainer.

Local work, interruption, and cancellation

Untracked files are left in place. A tracked file being excluded, or an existing file blocking an inclusion, is retained in .scribe/_state/recovery before removal or replacement. This includes clean tracked files: retaining their inodes protects against editors that still hold an open handle. Recovery and cached objects are not automatically purged, so shrinking a view does not guarantee an immediate reduction in total disk usage. Initial selective sync avoids downloading excluded content in the first place.

Opened paths affected by the transition are deferred. Opened additions outside the requested view also block activation, although they have no baseline to remove. Unchanged selected files retain their local edits. The active view and sync watermark remain unchanged until all required file operations complete and the server acknowledges the new workspace registration.

scribe status
scribe workspace view show
scribe revert Art/Characters/hero.psd
scribe sync

Revert preserves the tracked contents it replaces in recovery, modified or not; reverting an add leaves its untracked bytes in place. While a view transition is pending, new opening, move, reconciliation, merge, branch-switch, and submit operations are refused. Finish existing syncs, ordinary file resolution, branch operations, and pending moves before starting a view change.

To keep opened work and restore the active selection instead:

scribe workspace view --abort

Cancellation is another protected reconcile, not a destructive rollback. It can also be interrupted and resumed with scribe sync. It restores the selection; it does not rewind accepted history. Repository incarnation changes stop an in-flight transition; an explicit cancel reconciles the active selection against the restored repository's current head.

The client persists the target revision, incarnation, profile name, and resolved prefixes before changing files or registration. Partial plans are rebuilt before application, using completed baselines to avoid repeating file changes. Retries keep the pinned revision even if the branch advances. A lost registration reply leaves the local transition pending; sync repeats the same workspace registration before atomically publishing the active view and watermark.

workspace view show and workspace info work offline. status includes pending view details and recovery hints. With --json, an incomplete view change or sync returns one sync-report object with complete: false and a nonzero exit code; inspect failed and deferred, then use workspace view show for the selection.

Merging and cherry-picking support partial views; see partial-view integration for metadata-only excluded changes and explicit conflict inclusion. Profiles also select versioned repository mounts through their inclusion prefixes. Child workspaces sync independently at the parent’s recorded pins.

For server registration inventory, retirement from another computer, and remote lock administration, see workspace administration.

Expanding an active integration

During a ready merge or cherry-pick, view add and broader view set selections preserve completed resolutions and manual edits. The transition uses the integration's pinned target revision. Shrinking is refused. Resume an interrupted transition with sync, or undo the transition with workspace view --abort. See partial-view integration for grouped conflicts, recovery, and target-advance handling.