Skip to Content
GuidesWorktree Provisioning

Worktree Provisioning

Every feature runs in its own git worktree under ~/.shep/repos/<repo-hash>/wt/<branch-slug>. By default Shep creates it with git worktree add, which gives you a clean checkout: no node_modules, no untracked .env, no build caches.

That’s fine for most repositories. It isn’t for:

  • Monorepos that resolve dependencies from one hoisted node_modules at the root. A fresh worktree has none, and installing per feature is slow, or impossible offline.
  • Projects with native or path-sensitive tooling that only build from a prepared directory.
  • Teams with their own worktree tool that already knows how to lay a tree out correctly.

Two optional commands cover these cases. Leave both empty and nothing changes.

The two commands

SettingReplaces git worktree add?Runs inTypical use
Post-create commandNo, runs after itThe new worktreeLink node_modules, copy config, warm caches
Custom create commandYesThe main repositoryHand worktree creation to your own tool

Both are ordinary shell command lines, run through your platform’s shell (cmd.exe on Windows, the POSIX shell elsewhere), so pipes, &&, quoting and variable expansion work. When both are set, the create command runs first and the post-create command runs after it.

Both are global settings: they apply to every repository you use with Shep.

Configure them

In the web UI, open Settings → Worktree:

Settings → Worktree provisioning with a custom create command, a post-create command that symlinks node_modules, and a 900000 ms command timeout

From the terminal:

shep settings worktree # show the current config shep settings worktree --post-create-command '<cmd>' # run <cmd> in each new worktree shep settings worktree --create-command '<cmd>' # replace git worktree add shep settings worktree --timeout 900000 # per-command timeout, in ms shep settings worktree --clear # back to plain git worktree add

Passing an empty string (--create-command '') clears just that command.

Environment variables

Both commands get your normal environment plus:

VariableValue
SHEP_REPO_PATHAbsolute path of the main repository
SHEP_WORKTREE_PATHAbsolute path where the worktree must exist when the command finishes
SHEP_BRANCHBranch checked out in the worktree
SHEP_START_POINTStart ref for a new branch; empty when the branch already exists

SHEP_START_POINT tells a create command what to do: create the branch when it’s set, check out the existing branch when it’s empty. It’s empty, for example, when Shep adopts a branch you already have.

Examples

Leave the create command empty and set the post-create command:

shep settings worktree --post-create-command 'ln -s "$SHEP_REPO_PATH/node_modules" node_modules'

The post-create command runs inside the new worktree, so the relative node_modules link lands in the right place.

For a pnpm workspace where each package has its own node_modules, link them all:

for dir in packages/*; do [ -d "$SHEP_REPO_PATH/$dir/node_modules" ] && ln -s "$SHEP_REPO_PATH/$dir/node_modules" "$dir/node_modules" done ln -s "$SHEP_REPO_PATH/node_modules" node_modules

Paste multi-line scripts like this into the Post-create command field in Settings, or save them as a script in your repository and call that script.

Copy untracked local config

cp "$SHEP_REPO_PATH/.env.local" . 2>/dev/null || true

Use your own worktree tool

my-monorepo-tool worktree add "$SHEP_WORKTREE_PATH" "$SHEP_BRANCH" ${SHEP_START_POINT:+--from "$SHEP_START_POINT"}

A create command must leave a usable checkout at $SHEP_WORKTREE_PATH. Shep checks that the directory exists, then looks it up in git worktree list. If your tool made something git doesn’t list as a worktree of the main repository (a separate clone, for example), Shep inspects the directory directly instead of failing.

Prefer a tool that wraps git worktree add. Shep removes worktrees with git worktree remove, which only works on real worktrees.

Timeouts and failures

The timeout (default 300000 ms, five minutes) applies to each command separately. Raise it if your command runs an install.

A failing command fails feature creation. This is on purpose: a worktree that wasn’t set up properly causes confusing agent failures much later. The error shows the command, its exit message, and the first 2,000 characters of its output.

What’s next