---
id: "fluxos.git-worktrees"
titulo: "Repository worktrees"
resumo: "List and create parallel checkouts of the same repository without confusing them with Elyra workspaces."
idioma: "en"
tipo: "guia"
categoria: "arquivos-git"
aplicavelDesde: "0.0.16"
capabilities: ["git.worktrees.create"]
estadoEditorial: "aprovado"
nivelEvidencia: "artefato-distribuido"
refFonte: "27574c339b58316408f6be2d62169d59041d07bf"
revisaoFonte: "2026-09-24"
revisor: "mantenedor (v1, 2026-10-03)"
rota: "/docs/en/fluxos/git-worktrees/"
fonte: "pt-br/fluxos/git-worktrees.md"
caminhoPublico: "docs/publica/en/fluxos/git-worktrees.md"
hashFonte: "sha256:55218822988665440f9b9c3297da30739651aa47f3429cc60abc6c7072943375"
hashDestaPagina: "sha256:c4c9fe01be0dc3c3a794ef228ed966fb2ccfc275450f1b7d5c9309378129fc3c"
traducaoAssistidaPorIA: true
traducaoDesatualizada: false
corpoRetido: false
---
<!-- traducao-assistida-por-ia: idioma=EN fonte=pt-br/fluxos/git-worktrees.md fonteHash=sha256:55218822988665440f9b9c3297da30739651aa47f3429cc60abc6c7072943375 estado=atual -->

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

- [Git in Elyra: the repository belongs to the project](/docs/en/fluxos/git-conceito/)
- [Commit history](/docs/en/fluxos/git-historico/)