Settings
Per-Project Settings
Per-project settings are scoped to a single Spruce project. Edit them from Settings → Per-project settings (with that project open). Some fields travel with the project (shared via git), others are machine-local.
Shared project config: project.yaml
Settings stored in the project's project.yaml are pushed with the rest of the project:
| Field | What it is |
|---|---|
name | Project display name |
badge | Color badge for the sidebar (hex) |
baseBranch | The branch Spruce creates worktrees from. Default main. |
focusBarFilter | Rules for the focus bar (see The Focus Bar) |
defaultView | Name of the view loaded when the project opens |
codeRepositories[] | Shared metadata for each linked code repo (remote URL, display name) |
Machine-local config: workspace.yaml
Settings stored in workspace.yaml are per-machine and not pushed. They handle paths and local-only state:
| Field | What it is |
|---|---|
codeRepositories[].localPath | Where each linked repo is cloned on this machine |
worktreeStoragePath | Where Spruce creates worktrees for Start Working |
| Git identity | Per-project user.name / user.email if you override it here |
Linking code repositories
Under Settings → Code repositories, you can:
- Add an existing local path; Spruce records the path + remote URL.
- Clone a remote; Spruce clones and records both.
- Edit a linked repo's display name.
- Unlink a repo (leaves files on disk; it just forgets about them).
Each linked repo appears as a top-level root in the file tree on the Code page.
Focus bar filter
Define rules that drive which artifacts appear in the focus bar across every page. See The Focus Bar for available rule types.
Worktree storage path
By default, Spruce creates worktrees in a per-project directory it manages. You can set a custom path here, e.g. if you want all worktrees under ~/src/worktrees/<project>/.
Related
- Global Preferences — settings that apply everywhere.
- The Focus Bar — configuring the focus-bar filter.
- Branches and Worktrees — the worktree storage path in action.
- Open Your First Project — initial project setup via the wizard.