Worktrees

A worktree checks out another branch of the same repository into its own folder. With one worktree per agent, several agents can work on the same project at the same time without editing each other's files. PATerminal creates the worktree and opens it as a new session in one step.

Written for PATerminal v1.8.3

Create a worktree

  1. In a pane inside the repository, click Worktree in the pane bar (also in the branch list).
  2. Under Create from, choose Branch or Pull request.
  3. Pick the Base branch (or the pull request) and enter a New branch name.
  4. Choose Where to put it and, optionally, a session note.
  5. Press Create. A new session opens in the worktree's folder.

Where worktrees go

Outside the repository (default)
Worktrees are grouped in a folder named after the repository, e.g. ~/worktrees/acme-app/feature-login. Enter an absolute path, ~, or ... Your .gitignore is not touched.
Under the repository
Worktrees go in a folder inside the repository. If that folder isn't ignored yet, it's added to the root .gitignore (as a normal source change).

Copy ignored files

A fresh worktree has none of your git-ignored files, so it usually can't run yet. With Ignored files: Copy from this checkout (the default), PATerminal copies files such as .env, node_modules, and .venv from the current checkout into the new worktree, with a progress indicator. Choose Do not copy to skip it.

Worktree from a pull request

Choose Pull request as the source to list open pull requests (via your gh). PATerminal creates a worktree on the PR's branch and opens it as a session — ideal for reviewing or fixing a PR while your main checkout keeps working. An existing worktree for that branch is reused.

Manage worktrees

The worktree list in the Git window shows every worktree with its branch and state (current, main, locked, missing). Remove one, or select several and press Remove selected. Removing a worktree keeps its branch; the main and current worktrees can't be removed. Force remove is offered when Git refuses because of local changes.

Worktree defaults

Settings → Worktree defaults sets the default location and whether to copy ignored files. Turn on Automatically fill in the branch name to get a name made from the date, time, and a short random suffix. These defaults also apply when a worktree is created from an issue or by pair mode.

Still stuck?

Check the FAQ, or email us with your OS, PATerminal version, and what you tried. We reply to every message.

Read the FAQEmail support