Worktrees

Keep several checkouts organized, open a terminal or agent in the right one, and track worktrees across repositories.

A Git worktree is another working folder for the same repository. It lets you keep one branch open while another branch — or another coding agent — works in parallel, without switching the files underneath either task.

TermHQ gives you two views of them:

• The Worktrees section of the sidebar’s Git panel manages worktrees for the repository belonging to the pane you are focused on. A browser or SSH pane has no local folder, so the panel does not follow one.
• The Worktrees item in the status bar shows checkouts across every folder you chose to track, no matter which pane is focused.

Track worktrees across repositories

While no folder is tracked yet, Ctrl+Shift+T (⌘+Shift+T on macOS), or Worktrees in the command palette, opens Find your worktrees. It lists your favorite folders that hold checkouts, each with how many it holds, and Add a folder… picks any other folder with the system dialog. Select the folders you want and choose Track — the button counts them, as in Track 2 folders. TermHQ saves them as your worktree roots, scans them, and Find your worktrees grows into the full list. Not now or Esc closes it without saving anything. With nothing to suggest, it offers one large Choose a folder button instead. A long folder path keeps its start and its own name; hover or focus it to see it whole.

The card works from the keyboard alone, and its footer shows how:

• ↑ and ↓ walk the folders and carry on to the buttons; ← and → walk the buttons.
• Ctrl+↓ (⌘+↓ on macOS) jumps from the list to the buttons, and Ctrl+↑ jumps back. Home and End go to the first and last folder.
• Enter or Space checks a folder. Ctrl+Enter (⌘+Enter) tracks the checked ones.
• Esc is Not now.

You can also set the folders yourself: open Settings → Git → Worktree roots and add the folders that contain your repositories or worktrees. Type a path, or use Choose folder… to pick one with the system dialog. A folder that cannot be read is refused when you add it, with the reason.

As soon as at least one root is set, Worktrees appears at the far left of the status bar with the number of checkouts found. It comes first in the bar, ahead of the focused repository’s branch, so it stays put while the branch beside it changes with every pane you focus. No root means no scan and no status-bar item.

The scan looks for Git checkouts up to two levels beneath each root, which covers both common arrangements:

root/project
root/project/worktree

It does not crawl the rest of your machine. If one checkout belongs to a repository whose primary folder sits outside your chosen roots, TermHQ includes that folder in the repository’s card and labels it outside roots rather than searching beyond the roots.

Reading the Worktrees view

Click the status-bar item to open the full list. Its header sums it up — “12 checkouts · 5 repositories” — and once there is more than one checkout, a filter box narrows the list to the repositories, branches or folders matching what you type.

Each repository is a card: its primary checkout on top with a home mark, and its linked worktrees beneath it on connector lines. Every card is open by default. Fold one by clicking its header, with Enter on the header, or with ←; → opens it again. The folded state is remembered until that TermHQ window closes.

Each row shows:

• a mark for what it is: a home for the primary checkout, and for a linked worktree a branch, a lock when it is locked, or a commit when its HEAD is detached
• the branch, or a detached-head label
• a dot after the branch when the checkout has uncommitted changes
• the folder path
• tags at the end for what else is true: detached, locked, folder missing, or outside roots

Long names stay inside the window, and the list never scrolls sideways. A branch that does not fit ends in an ellipsis. A path gives way from its start, keeping its drive and its own folder name. While the list has the keyboard, the selected row scrolls a cut branch or path to its end and back so you can read it (with reduced motion it stays cut). Hover a row to see the whole branch and path.

After the view opens, TermHQ checks the worktrees one at a time. Each dot appears as its checkout is checked, so a long list can become useful immediately instead of making you wait for every folder.

A plain clone is the primary checkout, at the top of its card, and folders created with git worktree are linked worktrees. “Primary” describes its role in Git; it does not assume the branch is named main.

Click a checkout, or press → on it, to open its details beside the list: the full folder path (a long one wraps between folders, never inside a name), the branch it tracks and how far apart they are (such as “2 to push, 1 to pull”), its status — an operation in progress first, then conflicts, changed and staged files — the commit at HEAD with its author and age, and the last three commits. Every action is there as a button too, starting with Open terminal here. ↑ and ↓ walk the list and the details follow it. The arrow at the pane’s top right, ← or Esc puts the details away.

Open the right terminal or agent

Double-click a checkout, select it and press Enter, or choose Open terminal here in its details to open your default shell there. If TermHQ already opened a terminal for that checkout, the same action focuses it instead of creating another one.

Open the row menu with ⋯, right-click, or Shift+F10 to:

• choose a different installed shell
• open the folder in your IDE or file manager
• copy its path
• remove a linked worktree

When the row’s ⋯ button has keyboard focus, Enter opens that menu; it does not fold the repository’s card or open a terminal. With a checkout row selected instead, Enter keeps its open-or-focus-terminal action.

To start an agent there, open the row menu and right-click an “Open in <shell>” row, or click the chevron at its edge. Pick one of the installed agents from the flyout. TermHQ opens that shell in the checkout and starts the agent in it. In the details, the arrow beside Open terminal here opens the same list of shells.

Every removal asks first, and says what it means: the worktree’s folder is deleted, while the branch and its commits stay. Answer Keep it or Remove worktree. A checkout with uncommitted changes gets a second, separate question, because those changes would be lost — Force remove is the only way past it. The primary checkout is never offered for removal here. A locked worktree’s Remove worktree… is off, because Git keeps a locked worktree until it is unlocked (git worktree unlock in a terminal).

A worktree whose folder is already gone is tagged folder missing. Instead of removal, its menu and its details offer Prune missing worktrees, which drops Git’s entry for it — and for any other worktree of that repository whose folder is gone. Nothing on disk changes.

Create a worktree

Right-click a card’s header, or select it and press Shift+F10, and choose New worktree…. A form opens under the header:

• Branch — the new branch’s name. A name that is already one of your local branches checks that branch out as it is.
• Folder — fills in as you type the branch: beside the repository’s other worktrees, named after the repository and the branch, such as myapp-feature-login. Edit it and it stays as you typed it; clear it and it follows the branch again.
• From — the branch to start from, at first the one the primary checkout is on. Its list searches your local and remote branches.

The line under the form says what Create worktree will do, or why it cannot yet: a name Git would refuse, a branch already checked out in another worktree, or a folder a checkout already holds. If Git itself refuses, its reason takes that line. Enter creates the worktree and Esc cancels. The new worktree appears selected in its card, and the note that confirms it offers Open terminal.

Refresh and change the roots

The view refreshes when it opens, when your roots change, when TermHQ creates, removes or prunes a worktree, and when you return to the app, at most once every two minutes. Use Refresh, or press Ctrl+R (⌘+R on macOS) anywhere in the view, when you want an immediate scan. While a refresh runs, the status bar keeps the last count in place and turns its Worktrees mark into a spinning refresh symbol.

The gear in the Worktrees header opens Settings → Git → Worktree roots directly. Removing a root there asks Remove? first, and only stops tracking it; nothing on disk is changed. A root that has moved or disappeared stays in the list: the status-bar item turns to a warning, and the Worktrees view names the root it could not read, so you can repair it or choose Stop tracking, which takes it off the roots.

When git cannot read a checkout

A checkout git refuses to read, because another user account owns it, its folder is gone, or there is no permission, does not fill the view with errors. The scan folds them into one tinted line above the list, with a count. Open the line with its chevron to see each folder with the reason in plain words, the fix for git’s ownership refusal (safe.directory) stated once, and git’s own messages below.

The line’s × dismisses it until the folders it lists change. The header’s “N not read” brings it back.

Stop scanning these leaves those checkouts out of every scan from then on. TermHQ skips them without running git, so they cost nothing and warn no more. Settings → Git → Worktree roots lists them under Not scanned, each with Scan again.

Press Ctrl+Shift+T, or choose Worktrees from the command palette, to open the view without the pointer. On macOS, use ⌘+Shift+T. The view’s footer lists the keys it answers to.

An editor pane keeps that chord for Reopen closed tab while the editor is focused. Click the status-bar item, focus another pane, or turn off Settings → Editor → Editing shortcuts stay in the editor when you want the Worktrees view instead.

Repository worktrees in the Git panel

For the repository you are already reviewing, open the Worktrees section in the Git panel’s Changes view. You can create a sibling checkout on a new branch, open a terminal in an existing one, or remove a linked worktree without leaving the panel — with the same questions before a removal.

The global tracker is a view across repositories; it does not replace this repository-specific section.

What the tracker does not infer

The list tells you where checkouts exist and whether they have changes. It does not claim that an agent is running in a checkout. A terminal TermHQ opened from the list can be focused again, but the app does not inspect processes and guess which tool may be working there.