Worktrees

You can use the Worktrees tab to manage Git worktrees, separate working directory checkouts of the same repository. Use a worktree when you need to keep an in-progress branch untouched while you check out another branch. Each worktree is a separate folder with its own checkout, so your editor, terminal, and running processes don’t get disrupted.

Navigate the Worktrees tab

To open the Worktrees tab, click Git > Worktrees. Worktrees belong to the parent repository, so the tab always targets it, even when you opened it from a worktree’s own Project Tab.

Branches, Worktrees, and Tags each carry a Refs control beside their title. Use it to move between the three. The menu marks the one you are on, and choosing another opens it for this repository, or brings its tab forward when it is already open.

Worktree rows display the branch name and compact action buttons. Use Name or Activity to sort the list, and the search field to find a worktree.

In a narrow tab, the worktree names keep their space. Problem badges shorten first, then the action buttons are hidden, and then badges show only their icon. Every hidden action is also available in the expanded card.

Click a worktree’s title row or arrow to show its details. Only one worktree is expanded at a time; opening another closes the previous details. Details appear in an indented card with a different background from the title rows.

Click Collapse All beside the search field to close worktree details without hiding the list sections or clearing your search. Click the expanded worktree’s title row or arrow to close just that card. Clicking text inside the details keeps the card open.

The expanded worktree row displays the following information.

• Commit: The identifying hash of the most recent commit in the worktree.
• Message: The recent commit message on the worktree.
• Author: The recent author of the commit on the worktree.
• Date: The time since the recent commit was created.
• Branch: The branch of the worktree.

Worktrees are organized into the Favorites section and Other Worktrees section. To favorite a worktree, click the star icon next to the worktree name.

Create a worktree

You can create a worktree based on a new branch or on an existing branch.

You can start either flow from the Worktrees tab, or from the Branch control in the Project Header. In the Branch control, click New worktree… under Create.

To create a new worktree as a new branch, complete the following steps.

1. In the Worktrees tab, click New Worktree.
2. In the New Worktree dialog, click New Branch.
3. In Base Branch, choose the branch to base the worktree on. Click the arrow to open the list of local branches, or type to search it.
4. In the New Branch Name field, enter the branch name.
5. Click Create.

To create a new worktree based on an existing branch, complete the following steps.

1. In the Worktrees tab, click New Worktree.
2. In the New Worktree dialog, click Existing Branch.
3. In Branch, choose the branch. The list has Local Branches that no worktree has checked out, and Remote Branches that have no local branch with the same name. If you choose a remote branch, Zide creates a local branch that tracks it.
4. Click Create.

If you type a branch that the list leaves out, the field says why, for example that the branch is already checked out in a worktree. Create is unavailable until the field names a branch that you can use. Point to Create to see the reason.

The new worktree opens as a project tab with a worktree badge next to the parent project tab.

If worktree creation is interrupted

If Zide closes while creating a worktree, it checks that worktree the next time it starts. Zide does not overwrite files in the worktree.

• If the worktree is complete, its Project Tab opens.
• If the folder is empty, Zide continues the checkout.
• If creation is incomplete and the folder contains files, its Project Tab shows Worktree creation was interrupted. Click Open Worktree to open the worktree without changing any files. Missing or modified files appear as changes in Staging. To restore a missing or modified file to its committed version, discard its change in Staging.
• If the folder is gone or no longer belongs to the repository, Zide removes the record of the interrupted creation.

Click Close to close the Project Tab. The warning appears again when you open the worktree or restart Zide.

Worktree actions

In the expanded worktree row, click the following action icons to perform a worktree action.

Icon	Action
Switch	Switches to the worktree.
Launch	Opens the worktree in the file manager.
Path	Copies the worktree path.
Merge	Opens merge options, then merges the selected worktree branch into the repository’s current branch.
Rebase	Rebases the current worktree onto the selected worktree. In the Rebase Branch dialog, click Rebase.
Compare	Compares the difference in files between the current worktree and selected worktree in Diff view.
Copy	Copies the name of the worktree.
Lock	Locks a worktree to prevent deleting the worktree.
Delete	Opens the worktree removal dialog. Removing the folder does not merge, and the branch is preserved unless you explicitly choose branch deletion. For a worktree whose folder is missing, Delete removes its record immediately. See Prune stale worktrees.

Zide does not delete locked worktrees. To delete one, click Unlock first. Zide also does not delete a worktree if its folder differs from Git’s record or if Zide cannot check it for changes. If Git removes the worktree but its folder remains, Zide shows the folder path. Close any programs using the folder. Then delete the folder.

Before merging, Zide checks whether the merge could overwrite your changes. This check applies to Merge and Merge from default branch. If Zide blocks the merge, see A merge, revert, or cherry-pick did not start.

Repair a worktree

A worktree and its repository keep links to each other. If you move either folder outside Zide, the links break. The Worktrees tab shows the problem in a badge after the worktree name:

Badge	Meaning
Missing folder	The worktree folder is not where Git expects it. It was moved or deleted.
Drive unavailable	The drive or network location of the folder is not connected. The worktree can still be intact.
Link broken	The folder is in place, but it does not link back to the repository. Usually the repository folder moved.
Folder replaced	The folder no longer contains this worktree.

Expand the worktree to see its Status. A worktree with a problem cannot be opened as a project until you repair it.

To repair a worktree, click the wrench icon after its badge, or Repair… after its Status in the expanded card.

• For Link broken, Zide repairs the links immediately.
• For the other problems, the Repair Worktree dialog opens. If you moved the worktree, click Browse…, select the folder where it is now, and click Repair. Zide checks that the folder is this worktree before it changes anything, and tells you if it is a different worktree or repository.

Git updates only its links between the repository and the worktree. Files in the worktree do not change. The worktree keeps its favorite, and an open Project Tab for it opens again at the new location. If that tab has unsaved changes, Zide leaves it open at the old location. Save or close it, then open the worktree again.

If you moved the repository folder, several worktrees can show Link broken. To repair all of them, select More actions > Repair Worktrees. Zide lists the worktrees it repaired and any that still need attention.

If a worktree shows Drive unavailable, reconnect the drive. The problem clears when the Worktrees tab shows again. Zide does not prune a worktree on an unavailable drive. If Zide starts while the drive is unavailable, it does not open the worktree’s Project Tab, but it keeps the tab and opens it at the next start after the drive is back.

Repair uses git worktree repair, which needs Git 2.29 or later.

Prune stale worktrees

Git keeps metadata for worktrees whose folders were deleted outside Zide. To remove this metadata, select More actions > Prune Stale Worktrees in the Worktrees tab header. Zide lists what it will remove and asks for confirmation.

Prune does not remove a worktree whose folder still exists or whose drive is unavailable. To remove only the record of a single missing worktree, click Delete on its row. Zide removes the record immediately, without asking, so repair the worktree first if you moved it. For a worktree on an unavailable drive, Zide asks first. Delete never removes files in these cases, and it stops if the folder is available again.

Worktrees in the header

An ordinary repository Project Tab uses the Branch control. Worktree rows identify branches already checked out in worktrees, Create > New worktree… starts setup, and Manage > Worktrees opens the full Worktrees tab.

A worktree Project Tab uses a singular Worktree control for its own branch and lifecycle. Its styling reflects the current source state:

• Neutral means ordinary work is active.
• Cyan means the branch has committed work ready to merge into the repository’s default branch.
• Amber means the worktree needs attention, such as a detached HEAD, the default branch checked out in the worktree, or a Git operation in progress.
• Red means the worktree folder cannot be found.

Hover over the control for a summary of the current lifecycle state. For ordinary active work, that summary includes available ahead, behind, and uncommitted-change counts. The dropdown uses the same lifecycle color on its top border.

Worktree Project Tab

Open the Worktree control to see the current Worktree branch. Click View branch details to open that branch, expanded, in the Branches tab.

The dropdown provides these lifecycle actions:

• Merge from default branch merges newer commits from the repository’s default branch into the worktree. It is disabled with Already up to date when there is nothing to bring in.
• Finish worktree… opens the Finish worktree dialog. If a merge or rebase is already running in the worktree, finish that Git operation first.
• Branches and Worktrees open the full management tabs.

If the worktree has a detached HEAD or has the default branch checked out, the dropdown explains the condition and directs you to the Branches tab.

Finish a worktree

The Finish worktree dialog separates three choices:

• Merge into parent project merges the worktree branch into the branch currently checked out in the parent project. That parent branch is shown read-only. Switch it in the parent project before opening Finish if needed.
• Delete worktree removes the worktree folder and closes its Project Tab. It does not merge the branch.
• Also delete branch deletes the branch after its worktree is removed. It is unavailable for the default branch and whenever worktree removal is blocked.

The choices can be combined. For example, select Merge and Delete worktree to merge and finish while preserving the branch, or add Also delete branch to clean up the branch after a successful removal. Clearing Delete worktree also clears Also delete branch.

Each choice reports only the conditions that affect it. A merge is blocked by a detached HEAD, an unavailable parent branch, a Git operation in either project, or uncommitted parent-project changes. Unsaved or uncommitted worktree changes are not included in a merge. Worktree removal is blocked by unsaved editor files, an active Git operation, or a locked worktree; uncommitted worktree changes require an explicit loss acknowledgement. Zide rechecks the state after you confirm and performs cleanup only after any requested merge succeeds. If a Git hook or commit signing blocks the merge, Zide keeps the worktree. See Review a blocked operation.

Worktree lists in the header and Worktrees tab share Name and Activity sorting. Favorites remain grouped before other worktrees.