Skip to content
ELYRA

Repository worktrees

List and create parallel checkouts of the same repository without confusing them with Elyra workspaces.

View Markdown

A worktree is a second folder of the same repository, on another branch. It exists so that two lines of work don’t fight over the same files: each has its own checkout, with the same history underneath.

The Worktrees section

It lists the checkouts of the project repository. The list is read on demand — when you open the section and when you ask it to Re-read the repository worktrees — and that is why a worktree created just now in the terminal may not be there until you re-read.

Each item reports what you need to know before touching it:

  • whether it is the main one or an additional worktree;
  • the branch it has checked out;
  • its state: clean, with modified files, ahead of or behind the base, integrated;
  • exception signals: locked, orphan or bare;
  • a Git operation in progress (half-done merge or rebase).

The section also includes worktrees that Elyra did not create. That is intentional: the repository belongs to the project, and hiding a hand-made checkout would give a false view of what exists on disk.

Creating a worktree

  1. Open the Worktrees section and use New worktree.
  2. Provide the branch. The field searches the repository branches as you type and starts from the default configured in the repository.
  3. Provide the folder where the checkout will be born. There is a button to choose on disk.
  4. Optionally, write a command to run after creation. It runs inside the new folder — the field’s own example is pnpm install.
  5. Confirm in Create worktree.

There is an Open as workspace checkbox, and it is born unchecked: creating a worktree is creating a worktree; adopting it as an app workspace is a second decision, and it is yours. Checking the box is what makes the folder become an open workspace.

The post-creation command

That field runs real code in the new folder, with your credentials and your environment:

  • Use it for what is mechanical and known: installing dependencies, copying an environment file, preparing a hook.
  • Don’t paste into it a command you didn’t understand, nor one that came from an agent message without review.
  • If it fails, the worktree has already been created — the failure is the command’s, not the creation’s. You can run the command again in that folder’s terminal.

Local or on another machine

When the repository lives on another machine, the worktree is born there: the creation is routed through the host of the repository, and the folder you choose in the dialog is on the other side. Since the post-creation command also runs on the other side, it travels the same path — it is not your computer that executes it.

Limits and scope

  • The list is not a record kept by Elyra. It reflects the repository; removing a worktree from the terminal takes the item out of the list on the next re-read, and a worktree removed from outside may appear as orphan.
  • A worktree is not a workspace. No worktree is adopted as a workspace automatically, and the list does not show which folders are already app workspaces.
  • The branch name is validated by Git. An invalid branch or one already checked out in another folder is refused by Git itself, with its own message.
  • A worktree in use cannot be removed by Git. If the removal fails, check whether some terminal has that folder open.
  • Creating a worktree consumes disk. Each checkout is a working copy of the tracked files.

See also