Files and Git

Worktrees

Create, list, open and remove the Git worktrees of a project, and choose which files Orkestra copies into each new worktree.

On this page

A worktree is a separate Git checkout of your project. It has its own folder and its own branch. An agent can work in it and not touch your main checkout. Use the Worktrees module to create a worktree, to open a terminal or an agent in it, and to remove it when the work is done. Use the copy configuration to give every new worktree the local files that Git does not carry, for example an environment file with its own port.

Where to find it

  • Left sidebar, activity rail: the Worktrees icon (tooltip "Worktrees"). Click it to open the module. See Window layout for how modules open and close.
  • The module works on the active project. With no project it shows "Select a project to manage its worktrees."
  • The copy configuration window opens from the Copy configuration button in the module title bar.

What you see

Module title bar

  • Worktrees — the module title. Right of it, a number shows how many worktrees the project has. The number is hidden when the project has no folder.
  • Copy configuration button (copy icon, tooltip "Copy configuration (opens window)") — opens the copy configuration window.
  • Refresh from git button (refresh icon, tooltip "Refresh from git") — compares the list with Git.
  • ✕ button (tooltip "Close module") — closes the module. See Window layout.

Both module buttons are off when the project has no folder.

Toolbar

  • Text field — one field with two jobs. It filters the list, and it names a new worktree. The hint text is "Filter or name a worktree". When the list is empty, the hint is "Name a worktree" and the icon is a plus.
  • New button (plus icon) — creates a worktree with the name in the field.

Lines under the toolbar. Each one shows only when it applies:

  • A note about a missing folder (see "States and messages").
  • A red line that starts with "Can't create:". It gives the reason why the name is not valid.
  • A small hint line about a name that is already taken.
  • A red error note with a ✕ button (tooltip "dismiss error"). It shows why a create failed.
  • A count: "1 match" or "<number> matches".

Worktree list — one row for each worktree. The newest worktree is at the top. A row has, from left to right:

  • A coloured dot. Orkestra gives each worktree its own colour. The name of the worktree is in the next place, in a monospace font. Orkestra names the Git branch of a new worktree like the worktree.
  • The imported tag. It shows only for a worktree that Orkestra found in Git. It was created outside Orkestra. Tooltip: "Imported from git — this worktree was created outside the app".
  • The terminal button (tooltip "open a terminal in this worktree").
  • The trash button (tooltip "delete worktree").

The two buttons show only while the pointer is over the row, or while a live terminal runs in the worktree. In that second case the whole row also has a tint and a bar in the colour of the worktree. The row shows no branch, folder, status or port text. A click on the row does nothing.

Empty states

  • "No worktrees yet" and below it "Type a name and press New." — the project has no worktree.
  • "No worktree matches “<text>”." — the filter hides all rows.

How to

Create a worktree

Before you start, the project needs a folder, a Git repository and at least one commit.

  1. Open Worktrees in the left sidebar.
  2. Click the text field (hint "Filter or name a worktree").
  3. Type a name. Use letters, numbers, dot, dash or underscore.
  4. Click New.

Result: the field is empty again. A new row is at the top of the list. The count goes up by one. No terminal opens. If the create fails, an error note shows and the field keeps your text.

Tip: you can press Enter in the field instead of step 4.

Filter the list

  1. Click the text field in the toolbar.
  2. Type a part of a name. Capital letters do not matter.

Result: the list shows only the worktrees whose name contains the text. A line shows the number of matches. Do not press Enter or New here: that creates a worktree with this text as the name. Delete the text to show all rows again.

Open a terminal or an agent in a worktree

  1. Move the pointer over the row of the worktree.
  2. Click the terminal button (tooltip "open a terminal in this worktree").
  3. In the Open terminal in worktree menu, click the name of an agent, or click Shell.

Result: a new terminal opens on the active workbench. Its folder is the worktree. An agent starts in it at once. No dialog opens. A launcher with its own variables or arguments keeps them. The terminal title is the name of the launcher, or "shell". The menu closes.

Open a terminal by dragging a worktree onto the canvas

  1. Press the mouse button on the name of the worktree in the list.
  2. Drag the name over the canvas of a workbench.
  3. Release the mouse button.

Result: a new terminal opens at the drop point. Its folder is the worktree. It uses the launcher that is set in Settings → Task Defaults → Default launcher. When no launcher is set, or the launcher does not exist any more, a plain shell opens. See Starting terminals and agents and Settings: task defaults and engines.

Refresh the list from Git

  1. Click Refresh from git in the module title bar.

Result: Orkestra reads the worktrees that Git knows for the project. It removes a row when Git no longer lists the folder of that worktree. Terminals of such a worktree stay open, but they are no longer linked to it. It adds a row, with the imported tag, for each Git worktree that Orkestra did not know. The row name is the name of its folder. When nothing differs, nothing changes and no message shows.

Remove a worktree

  1. Move the pointer over the row of the worktree.
  2. Click the trash button (tooltip "delete worktree"). You can also open the terminal menu and click Delete worktree.
  3. If the dialog Remove worktree? opens, click Remove.

Result: the row leaves the list. Orkestra deletes the worktree folder and its branch on disk (see "Limits and tips"). Terminals that were open in the worktree stay open and lose the link to it.

The dialog opens only when the worktree still has an open terminal or an open file window. A worktree with no open windows is removed at once, with no question.

Open the copy configuration window

  1. Click Copy configuration in the module title bar.

Result: the window Worktree copy configuration opens over the app. It shows the configuration of the active project. Each project has its own configuration.

Copy a file into every new worktree

Before you start, open the copy configuration window.

  1. Click Add file.
  2. Click the path field of the new card (hint "path/to/file.ext").
  3. Type the path of the file, from the project folder. Or click the folder button of the card (tooltip "Browse") and choose the file.
  4. To copy the file without changes, leave the rule row empty.
  5. Click Save configuration.

Result: the window closes. Each new worktree of the project gets a copy of the file.

Give each worktree its own port

Before you start, add a file card as in the last recipe.

  1. In the Find value field of a rule, type the port number that the file contains, for example 5171.
  2. In the Kind list, keep Port.
  3. In the Token name field, type a label, for example PORT_1.
  4. Click Save configuration.

Result: when Orkestra creates a worktree, it picks a free port from 41000 to 42000. It writes this port in the copied file in place of the number. The same label gives the same port in all files of that worktree. Two different labels give two different ports. Two worktrees never get the same port.

Replace another value in a copied file

Before you start, add a file card.

  1. Click Add rule in the card.
  2. In the Find value field of the new rule, type the text to find.
  3. In the Kind list, choose Host, Var, Path, Secret or URL.
  4. In the Token name field, type the new text.
  5. Click Save configuration.

Result: the copy of the file has the new text in place of the text you typed in step 2. The kinds other than Port are only labels for you. They all work the same way.

Copy a folder into every new worktree

Before you start, open the copy configuration window.

  1. Click Add directory.
  2. Click the path field of the new card (hint "path/to/directory").
  3. Type the path of the folder, from the project folder. Or click the folder button of the card (tooltip "Browse") and choose the folder.
  4. Click Save configuration.

Result: each new worktree gets a copy of the folder and all files in it. The files are not changed.

Remove an entry from the copy configuration

  1. In the card or the rule row, click the ✕ button. The tooltip is "Remove file", "Remove directory" or "Remove rule".
  2. Click Save configuration.

Result: new worktrees no longer get that entry. The last rule of a file cannot be removed: its ✕ button is off.

Close the copy configuration window without saving

  1. Click Cancel.

Result: the window closes and Orkestra drops your changes. The ✕ button of the window (tooltip "Close"), the Esc key and a click outside the window do the same.

Make the copy configuration window larger

  1. Click the fullscreen button in the window title bar (tooltip "Fullscreen").

Result: the window fills more of the screen. The tooltip of the button changes to "Restore". Click it again to go back.

States and messages

Project and Git requirements

  • Without a project folder, the name field, New and the title-bar actions are disabled. Attach a location through the project switcher.
  • If the folder is not a Git repository, the list is replaced by an Initialize Git prompt. Use Details to inspect Git's response and Retry if initialization fails. A worktree also needs at least one commit to branch from.
  • While creation runs, the name field and New are disabled. An empty field is allowed because it also filters the list.

Names and create failures

  • Names may contain letters, numbers, dots, dashes and underscores; they cannot start with a dash, contain .., or exceed 128 bytes. If a name is already taken, Orkestra appends a number such as -2 and shows the final name.
  • A red create note names the failed stage: Create worktree, Copy files or Replace ports. Git errors can mean the repository has no commit or Git rejected the operation. Copy errors identify an outside-project path, a denied folder such as node_modules, or a file/count/total-size limit; see Limits and tips. A port replacement error means the rule needs a token name. If the 41000–42000 range is exhausted, choose another available port setup or retry later. A failed create leaves no worktree folder behind.
  • A red remove note means Git refused to remove the worktree; the row stays so you can retry. Remove worktree? appears only when a terminal or file window is open there. It explains that those windows stay open and terminals detach if you continue.

Copy configuration

  • Each new worktree copies configured files with replacement rules and directories verbatim. A new file entry starts with a Port rule. Paths must be nonempty. A rule may be left blank and is dropped on save; if only one side of a value/token pair is filled, Save configuration stays disabled until you fix it.
  • A worktree row is tinted while a live terminal runs there. An accent ring and flash show when you jump to it from Terminal info.

Limits and tips

  • A new worktree starts from the latest commit of the branch that the project has checked out. Changes that you did not commit are not in it.
  • Orkestra makes the worktree folder inside the project folder, in a folder named .worktrees. It also adds that folder to the Git ignore list of the project, when it can.
  • Remove deletes the worktree folder with everything in it, also changes that you did not commit and files that Git does not track. Orkestra also deletes the branch of the worktree with force, also when you did not merge it. Commits that are only on that branch are then lost from every branch. A worktree whose branch you changed keeps its branch.
  • The copy configuration is for the whole project. It acts on new worktrees only. It does not change a worktree that exists. It also acts on a worktree that Orkestra makes when you launch a task in a new worktree. See Starting terminals and agents.
  • A rule changes text files only. Orkestra copies other files as they are. A file entry can name a folder too: then all files in it are copied and the rules act on its text files. A rule replaces text in one pass, longest match first. A new text is never replaced again.
  • Orkestra skips a file that is not in the project, and shows no message. A path outside the project is refused with an error.
  • A copied folder must not contain a folder named .git, node_modules, .venv, venv, .worktrees or pycache. If it does, the create fails.
  • Limits for one create: 16 MiB for one file, 2000 files, 256 MiB in total.
  • The list shows no port. A worktree that Orkestra imported from Git has no assigned ports.
  • A terminal in a worktree shows the colour of the worktree on its title bar, unless you gave that terminal its own colour. See Canvas windows.
  • Drop the name of a worktree into a terminal to type a link to it for the agent. See Drop a file, task, worktree or session into a terminal. The Helm message box and the text editor of a file window accept the same drop.
  • To link a worktree to a task, see Task window. To launch a task in a worktree, see Starting terminals and agents. To remove a project together with its worktrees, see Projects.