User guide

Worktrees Partly available

A worktree is a second folder of the same repository, with its own checked-out branch. You can work on two branches at the same time, each in its own window, without switching branches in one folder. The Worktrees section of the sidebar lists them all.

The Worktrees section#

The Worktrees section sits under the branch tree in the sidebar. The main checkout, the folder you opened the repository from, is always the first row. The other worktrees follow it. Each row shows the worktree's branch, or a detached HEAD.

Click the header to fold the section. The + in the header stays available while it is folded. See Branches.

Each worktree gets a color from its name, so the same worktree keeps the same color in every session.

Badges mark the state of a row:

The + button in the section header starts a new worktree. On a linked worktree row, a × appears when you point at the row. It removes that worktree with the same checks as Remove Worktree.

Create a worktree#

1. Choose Create Worktree in the menu of a branch. The dialog opens with that branch chosen. Or choose New Worktree… from the + button or the command palette. The dialog opens empty.
2. Choose how the worktree starts. The dialog has three modes:
   • Existing branch: a branch that has no worktree yet.
   • New branch: a new branch, created from a commit.
   • Detached HEAD: a commit, with no branch.
3. Check the folder. GitMaster suggests a folder next to the repository, named <repo>-<branch>. A / in the branch name becomes -. The suggestion follows the branch name until you type a different folder.
4. Click Create worktree. The command appears in the Git commands panel.

The branch field suggests local branches as you type.

Example: a second worktree for a review#

1. Right-click a branch that is not checked out, such as feature/login, and choose Create Worktree.
2. Choose Existing branch. The branch field shows the branch you picked.
3. Leave the folder as suggested: ../myproject-feature-login, next to the repository.
4. Click Create worktree. The row appears in the Worktrees section.
5. Double-click the new row. It opens in its own window.

The folder#

GitMaster follows these rules for the folder:

• The folder must not exist. GitMaster refuses an existing folder, even an empty one, with the same message Git gives.
• Any other error from Git appears in the dialog exactly as Git wrote it.

A branch that another worktree uses#

Git refuses to check out a branch that a worktree already uses. The dialog shows Git's message and the button Open that worktree. Choose it to open that worktree in its own window instead.

Open a worktree in its own window#

1. Double-click a worktree row. It opens in a new window.
2. Each worktree has its own window. The window you came from does not wait for it and stays as it is.

Double-clicking the here row does nothing. A row whose folder is missing shows a message in the status bar instead.

Open Worktree does the same from the row menu and from the command palette.

Move a file to a worktree#

Drag a changed file from the Working Copy and drop it on a worktree row. The change is applied in that worktree, unstaged and uncommitted, and the file leaves the Working Copy you dragged it from. The target may already have changes: the move is refused only when they conflict. Drop the file on the section header or on + to move it into a new worktree. The rules are on the Working Copy page.

Remove a worktree#

1. Right-click the row and choose Remove Worktree. Or point at a linked worktree row and choose ×. In the command palette, choose Remove Worktree and pick the worktree with Tab.
2. Read the dialog. It checks the worktree and lists what would stop the removal.
3. If a blocker can be overridden, tick the confirmation checkbox. The checkbox names what will be discarded. The remove button stays disabled until you tick it.
4. Click Remove worktree.

GitMaster checks the worktree again when you remove it, so the dialog never acts on an old answer.

GitMaster removes the folder with git worktree remove. It never deletes the folder by hand. Files that Git ignores inside the folder are removed with it.

Lock and unlock#

Choose Lock Worktree or Unlock Worktree in the row menu, whichever applies. The command palette has both as well.

A locked worktree is blocked from removal until you unlock it or tick the confirmation checkbox. Pruning leaves it out. If Git refuses the lock or the unlock, for example because the worktree is already locked, Git's message appears in the status bar.

Prune worktrees#

Pruning clears the records of worktrees whose folders are gone.

1. On the row of a missing worktree, choose Prune Worktrees. You can also choose it in the command palette.
2. The dialog, titled Prune worktrees?, lists each stale record with the reason Git gives. Nothing has changed yet.
3. Click Prune to remove the records.

Pruning removes Git's records only. It never touches a folder. A locked worktree is left out of the list. If the list changed after the dialog showed it, the prune is refused. Open the dialog again to see the current list.

Branch menu for a worktree branch#

When a branch is checked out in a linked worktree, its branch menu offers worktree actions instead of the usual ones. In order, the menu has:

• Open Worktree
• Reveal Worktree in File Manager
• Copy Worktree Path
• New Branch…
• New Child Branch, Set Parent…, Remove From Stack, Reparent to Grandparent and Restack This Stack, in the Stacks preview feature (see Stacks and restack)
• Remove Worktree, in red

Checkout Branch, Rename Branch, Delete Branch, Push With Lease and Create Worktree are not in this menu, because the branch already has a worktree. The main checkout keeps the normal branch menu.

From the shell#

gitmaster worktree lists worktrees by path or by branch, finds the worktree of a branch and creates one, from a terminal or a script. It also brings ignored files such as .env into a new worktree with links, as listed in a .worktreeinclude file, instead of copying them. See Command line.

Open in a terminal#

Worktrees and agents#

Worktree actions in the command palette#

Open the palette with Ctrl+K (⌘K on macOS). For the actions that need a worktree, press Tab and pick one.

The rules of Command palette apply to every step.