MergepondDownload

Git worktrees tutorial

Work on several branches at once, each in its own folder, without stashing or cloning twice.

This guide is an outline. Each section lists what it will cover; the full text arrives before launch.

What a worktree is

  • One repository, several working folders. Each folder has its own checked-out branch, index and files.
  • They share one .git object store, so a new worktree takes seconds and almost no disk.
  • Why it beats git stash and a second clone when you switch tasks often, review pull requests, or run coding agents in parallel.

Create your first worktree

git worktree add ../api.worktrees/fix-flaky-tests -b fix/flaky-tests
  • Picking a folder layout that stays tidy: ../<repo>.worktrees/<branch-slug>.
  • Starting from an existing branch, a remote branch, or a pull request (git fetch origin pull/123/head:pr-123).
  • What happens to .env files, node_modules and other untracked files (they are not copied).

List, move and remove worktrees

git worktree list
git worktree move ../api.worktrees/fix-flaky-tests ../api.worktrees/flaky
git worktree remove ../api.worktrees/flaky
git worktree prune
  • Why Git refuses to check out the same branch twice, and what to do instead.
  • Cleaning up after a merge: removing the folder and deleting the branch.
  • Locking a worktree on a removable drive with git worktree lock.

Worktrees and your tools

  • Editors and language servers: open each worktree as its own project.
  • Package managers: install per worktree, or link a shared store.
  • Hooks and config: what is shared (.git/config, hooks) and what is per worktree (git config --worktree).

Worktrees for coding agents

  • Give each agent its own worktree and branch so they never edit the same files.
  • Review an agent's work by diffing its branch, then merge or discard the whole worktree.
  • Keeping track of which agents are still working, which need review, and which are merged.

Doing the same in Mergepond

  • New worktree from a branch or pull request in one step, with the folder picked for you.
  • Setup recipes: copy .env files, link node_modules, run your install command.
  • The worktree board: working, ready for review, merged and safe to remove.
  • Worktrees on other machines over SSH (Pro).

Troubleshooting

  • fatal: '<branch>' is already checked out at …
  • A worktree folder deleted by hand: git worktree prune.
  • Submodules and Git LFS inside worktrees.