Worktrees and worktree setup
A worktree checks out another branch of the same repository in its own folder, so you (or a coding agent) can work on it without stashing or switching the main folder. Mergepond creates worktrees, names their folders from a pattern, and can set each one up with a recipe.
Where to find it
- Toolbar › New worktree, or ⌘N.
- File › New Worktree… and File › New Worktree from Pull Request… (⌘⇧N).
- Command palette › Worktrees: Create worktree from a branch, Create worktree with a new branch, Create worktree from a pull request, Worktree settings…
- Worktrees tab (⌘3): the New worktree button and the gear for worktree settings.
- Sidebar › Repositories: each worktree is listed under its repository.
The New worktree sheet
The sheet says what it does: it checks out a branch in its own folder, so the current one stays as it is. Pick a source with the segmented control at the top.
| Source | Fields | What Mergepond does |
|---|---|---|
| New branch | Name (for example agent/claude-3), Starts from (default HEAD) | Creates the branch at the starting point and checks it out in the new folder. |
| Existing branch | Branch (feat/something or origin/feat/something) | Checks out a local branch, or creates a local branch tracking the remote one you typed. |
| Pull request | Pull request number (for example 412) | Fetches pull/<n>/head from the default remote into a branch named pr-<n>, then checks that out. |
Under the source fields:
- Folder follows the folder pattern (below) until you edit it. Once edited it stays as you typed; the "Use the pattern" link puts the pattern back.
- Run the setup recipe (ticked by default) runs the recipe after checkout. A line under it summarises the recipe, such as "Copies .env, links node_modules, runs pnpm install." or "The recipe is empty." The Edit recipe link opens worktree settings.
- Create worktree creates it. Cancel closes the sheet.
The sheet refuses to continue without the one thing it needs: "Pick a branch to check out.", "Type a name for the new branch." or "Type the pull request number, like 412." Mergepond also stops if the branch doesn't exist ("There's no branch called …"), the name isn't a valid branch name, or the folder already exists ("… already exists. Pick another folder.").
While the recipe runs
If a recipe is set, the sheet turns into a progress view titled "Setting up name". Each step is listed with its last few lines of output. You can close the sheet at any point: setup carries on, and the worktree board shows its progress. When it finishes the title becomes "Worktree ready", or "Setup stopped" if a step failed, with the note that you can open the worktree in Terminal and run the step there to see the full output. The footer offers Open in a new window and Done.
Without a recipe, the worktree is created straight away and a toast says where it went: "Created the name worktree in path."
Worktree settings
Worktrees tab › gear or Command palette › Worktree settings… opens the settings for this repository. The sheet is headed "Worktree settings" and says what it covers: where new worktrees of the repo go, how each one is set up, and how coding agents use them. The settings are saved in a file at the root of the repository, .mergepond.local.toml for you alone or .mergepond.toml for the whole team, so each repo has its own and pond reads the same ones. Project settings files describes the files.
| Setting | Key | Default | What it does |
|---|---|---|---|
| Folder pattern | location under [worktrees] | ../<repo>.worktrees/<branch> | Where each new worktree folder goes. <repo> is the main folder's name and <branch> is the branch with /, \ and spaces turned into -. Relative paths are relative to the main folder; ~/ and absolute paths work too. The pattern must contain <branch>, so every worktree gets its own folder. |
| Copy | copy under [setup] | Empty | Files that aren't in Git, copied from the main folder (for example .env). Globs are matched against the main folder's untracked and ignored files. |
| Link | link under [setup] | Empty | Folders shared with the main folder through a symlink (for example node_modules). The link is also added to the worktree's .git/info/exclude, so it never shows as a change. |
| Run | run under [setup] | Empty | Commands run in the new folder, in order, through your login shell. Setup stops at the first command that fails. |
| Coding agents | isolation under [agents] | Ask me the first time | Whether a coding agent using pond works in a worktree: Always in a worktree, Only when I ask, or Ask before each task. See The isolation choice. |
| Agent branch names | branch under [agents] | agent/<agent>/<task> | How a branch is named when an agent starts a task. <agent> becomes claude-code or codex, <task> a few words about the task. Must contain <task>. See Agent branch names. |
Under the fields, Share with the team chooses the file. Unticked, the hint reads "Saved in .mergepond.local.toml, which only you have. Git ignores it." and Save shows "Saved the worktree settings." Ticked, it reads "Saved in .mergepond.toml at the top of the repo. Commit it, and everyone gets these settings." and Save shows "Saved to .mergepond.toml. Commit it to share it." With the default pattern, worktrees of ~/src/api land in ~/src/api.worktrees/<branch>, beside the main folder rather than inside it.
In the sidebar and the switcher
Each repository in Sidebar › Repositories lists its worktrees underneath. Clicking one opens it in this window; ⌘-click opens it in a new window. A tag beside the name shows its state: Merged, Missing, Gone, Setting up, or the paused operation. The repository switcher (⌘P) lists worktrees as "folder (branch)".
Free and Pro
Creating, opening and removing worktrees, the recipe and worktree settings all work on Mergepond Free, as does pond, the command line tool and MCP server that makes worktrees for coding agents. From 1.0.7 the board view of the Worktrees tab, with its states, layouts and Clean up, is part of Pro; on Free the tab is a plain list. See Worktree board: Free and Pro.