MergepondDownload
Mergepond
Download for Mac

Free for local repos. macOS 13 or later.

Worktrees that set themselves up

A fresh worktree has the branch's files and nothing else: no .env, no node_modules, no build. This guide sets a folder pattern and a setup recipe once, so every worktree you create afterwards is ready to run the moment the sheet says "Worktree ready".

Updated 10 November 2026

Where the settings live

Open the repository and press ⌘3. In the board's header, the gear button is "Worktree settings: folder pattern and setup recipe". The same sheet opens from ⌘K with "Worktree settings…", and from the "Edit recipe" link in the new-worktree sheet.

The settings are saved in a file at the root of the repository. By default that is .mergepond.local.toml, which Mergepond keeps out of Git, so your teammates do not inherit your paths. Tick Share with the team at the bottom of the sheet and they go to .mergepond.toml instead, which you commit, so everyone who clones the repository gets the same recipe. Every worktree of the repository shares them either way. If you set these up before Mergepond 1.0.6 they are in the repository's Git config; Mergepond still reads them there and moves them into the file the next time you save. Project settings files lists every key.

Choose a folder pattern

  1. Open Worktree settings. The "Folder pattern" field holds ../<repo>.worktrees/<branch> by default.
  2. Keep or change it. <repo> becomes the main folder's name and <branch> the branch name with slashes and spaces turned into dashes, so feat/search on a repository at ~/src/api becomes ~/src/api.worktrees/feat-search. The path is relative to the main folder, and it must contain <branch> so two worktrees cannot land in the same place.
  3. Click Save.

A sibling folder keeps worktrees out of the repository itself, which matters: a worktree inside the main folder would show up as untracked files in every other view.

Write a setup recipe

A recipe has three parts, run in this order when a worktree is created.

  1. Copy: untracked or ignored files to copy from the main folder into the new one. .env is the usual one; add .env.local or a config/local.yml if you have them. Mergepond copies the file as it is in your main folder today.
  2. Link: folders to symlink from the main folder rather than copy. node_modules is the point of this; a link appears instantly and shares the installed packages. Link only things you are happy to share between worktrees, because a change in one is a change in all.
  3. Run: commands to run in the new folder, in order, each through your login shell ($SHELL -lc), so your PATH, nvm and the rest apply. pnpm install is the placeholder. The list stops at the first command that fails.
The board while a worktree is being set up: the card reads Setting up until the recipe finishes.

Create a worktree and watch it set up

  1. Press ⌘N. Under the Folder field the sheet says "Run the setup recipe" with a summary of what it will do, such as "Copies .env, links node_modules, runs pnpm install." Leave it ticked.
  2. Click "Create worktree". The sheet title changes to "Setting up" followed by the branch name, and shows the recipe's progress.
  3. When it is done the sheet says "Worktree ready" and offers "Open in a new window". If a command fails, it says "Setup stopped" and shows the last twelve lines of output.
  4. You do not have to wait. Close the sheet and the card on the board shows "Setting up" until the recipe finishes.

If setup fails, a toast names the branch and the step: "Setting up agent/claude-3 failed at “pnpm install”. Run it in Terminal to see why." The worktree exists and the branch is checked out; only the step that failed, and anything after it, did not run. Fix the cause, open the worktree in Terminal from its card, and run the remaining commands by hand, or remove the worktree and create it again.

Get more from it

  • Untick "Run the setup recipe" for a worktree you only want to read, such as a pull request you are reviewing. The checkout is faster and nothing is installed.
  • Recipes run on the machine that holds the repository. For a repository opened over SSH (Pro), pnpm install runs on that host, in the new folder there.
  • Keep the Run list short and idempotent. A recipe that generates code or starts a database is a recipe that fails on the day you are in a hurry.
  • The same recipe runs for worktrees created from a pull request number (⌘⇧N), so reviewing a pull request can mean a worktree that is already built.