Worktrees and isolation

worktree creates a separate Git workspace per run; shared uses the base folder. Both require Git with a resolvable base commit. Worktrees default to the sibling .cockpit-worktrees/ folder.

Create .cockpit-worktree.json at the root of the project being worked on:

{
  "worktree": {
    "sharedDirectories": ["node_modules"],
    "copyFiles": [],
    "allowEnvCopy": false,
    "excludeDirectories": ["dist", ".next", ".cache"],
    "setupCommands": ["git status --short"]
  }
}

The outer worktree key is optional. Defaults share node_modules and do not copy environment files. Copying .env* requires allowEnvCopy: true. Escaping containment or sharing forbidden directories is rejected.

Do not share .cache, dist, .next, .vite, build, target, out, .git, or .cockpit. setupCommands and excludeDirectories are accepted and validated, but the current Isolation Core neither executes those commands nor performs exclusions from that list. Use your project's own dependency and output cleanup workflow.

Shared dependency changes affect every workspace using the target. For dependency changes, consider sharedDirectories: [] and separate installations per workspace. Worktrees do not install all dependencies automatically.

Full template: docs/templates/.cockpit-worktree.json.