Worktrees

Every git worktree of your project gets a folder of its own in the left column. Its card shows the branch, unpushed work, pull request, and CI checks, and the terminals you open in it start in that worktree.

Terminay Folders list with the General folder on main and a linked worktree folder, each showing its changes and terminals

Worktrees Are Folders

In a project whose root is a Git checkout, the General folder is that checkout, and every other worktree of the repository has a linked folder. Terminay creates the folder as soon as it sees the worktree, however it was made: by you, a script, or an agent.

Select a linked folder to show its own panel layout. The sidebar's Files pane and Changes pane follow it, so you browse and diff that worktree without changing the project's root. A terminal created in the folder, from its New terminal row or one of the agent buttons beside it, starts in that worktree.

A project that is not a Git repository has General and any plain folders you make, with no branch lines. See Workspace for folders in general.

Reading A Folder Card

  • Label: a linked folder is named by its branch, or by its directory when the worktree is detached. When two checkouts share a branch, the directory name follows in a muted colour. The label follows the worktree when it switches branch.
  • Branch line: General shows the project checkout's branch beneath its title.
  • Dirty: the branch is drawn in the accent colour when the checkout holds work that exists only on this machine: uncommitted or untracked changes, or unpushed commits.
  • Unmerged: an upward arrow and a count when the branch has commits the default branch lacks, pushed or not.
  • Facts line: the size of the unpushed work in lines added and removed, missing when the worktree is gone from disk, the pull request as PR # and its number (with its state when it is not open), no PR for unlanded work without one, and the CI checks.

Choose the pull request chip to open the pull request, and the checks chip to list each check beneath the card. Hover the label for a tooltip with the full path, branch, HEAD, and counts. A card says Pulling… or Deleting… while that is happening.

Pull Requests And Checks

The bundled Gitea and GitHub extensions fill in each worktree's pull request and CI checks. They detect the forge from the origin remote, so there is nothing to configure per project. A merged pull request shows as merged, in purple.

For Gitea and Forgejo, Terminay reuses an existing tea CLI login for that server; otherwise it asks for an access token with read access to repositories. The token is stored on the Terminay Server, per forge. The same pull request and checks also appear on Home dashboard cards.

Worktrees An Agent Creates

When a command in a terminal creates a worktree, Terminay creates its linked folder and moves that terminal into it, so the agent that made the worktree keeps working where you can see it. Terminay works this out from the terminal's process tree and Git alone, so it behaves the same for an agent, a script, or you. Move the terminal back whenever you like; Terminay will not move it there again.

Turn off Move terminals into new worktree folders in Settings → Shell to keep terminals where they are. The folder still appears, and offers to take the terminal.

Worktree Actions

Open a folder card's actions menu with the vertical dots on its header, or right-click it:

  • Commit & push with AI…: start Quick Push for this worktree.
  • Pull from origin: pull the worktree's branch when Git allows it.
  • Rename worktree: rename the worktree's folder on disk. The folder stays linked to it.
  • Delete worktree: permanently remove the worktree folder, including uncommitted and untracked files. If the folder still holds terminals or tabs, the one question also asks whether to move them to General or close them.
  • Copy path and Copy relative path.
  • Open shell in folder: open a new terminal in that worktree.
  • Reveal in OS: show the worktree folder in your file manager.

To clear out finished work in one go, open the menu in the Folders header and choose Delete all clean worktrees. Terminay lists every worktree it will remove before you confirm, and skips any that gained changes in the meantime.

General offers the same menu without Rename and Delete. A linked folder can only be removed by deleting its worktree. If a worktree disappears outside Terminay, its terminals move to General, still running, and the folder goes.