---
id: "fluxos.git-worktrees"
titulo: "Worktrees do repositório"
resumo: "Liste e crie checkouts em paralelo do mesmo repositório sem confundi-los com workspaces do Elyra."
idioma: "pt-br"
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/pt-br/fluxos/git-worktrees/"
fonte: "pt-br/fluxos/git-worktrees.md"
caminhoPublico: "docs/publica/pt-br/fluxos/git-worktrees.md"
hashFonte: "sha256:55218822988665440f9b9c3297da30739651aa47f3429cc60abc6c7072943375"
hashDestaPagina: "sha256:55218822988665440f9b9c3297da30739651aa47f3429cc60abc6c7072943375"
traducaoAssistidaPorIA: false
traducaoDesatualizada: false
corpoRetido: false
---
Uma **worktree** é uma segunda pasta do mesmo repositório, em outra branch. Ela existe para que duas
frentes de trabalho não disputem os mesmos arquivos: cada uma tem o seu checkout, com o mesmo histórico
por baixo.

## A seção Worktrees

Ela lista os checkouts do repositório do projeto. A lista é lida **sob demanda** — ao abrir a seção e
quando você pede **Reler as worktrees do repositório** —, e por isso uma worktree criada agora há pouco
no terminal pode não estar ali até você reler.

Cada item informa o que se precisa saber antes de mexer:

- se é a **principal** ou uma worktree adicional;
- a **branch** que ela tem em checkout;
- o **estado** dela: limpa, com arquivos alterados, à frente ou atrás da base, integrada;
- sinais de exceção: **bloqueada**, **órfã** ou `bare`;
- uma operação de Git em andamento (merge ou rebase pela metade).

A seção também inclui worktrees **que o Elyra não criou**. Isso é intencional: o repositório é do
projeto, e esconder um checkout feito à mão daria uma visão falsa do que existe no disco.

## Criar uma worktree

1. Abra a seção **Worktrees** e use **Nova worktree**.
2. Informe a **branch**. O campo busca nas branches do repositório conforme você digita e parte do
   padrão configurado no repositório.
3. Informe a **pasta** onde o checkout vai nascer. Há um botão para escolher no disco.
4. Opcionalmente, escreva um **comando para rodar depois de criar**. Ele executa dentro da pasta nova —
   o exemplo do próprio campo é `pnpm install`.
5. Confirme em **Criar worktree**.

Há uma caixa **Abrir como workspace**, e ela nasce **desmarcada**: criar uma worktree é criar uma
worktree; adotá-la como workspace do app é uma segunda decisão, e é sua. Marcar a caixa é o que faz a
pasta virar um workspace aberto.

## O comando pós-criação

Esse campo roda **código de verdade** na pasta nova, com as suas credenciais e o seu ambiente:

- Use-o para o que é mecânico e conhecido: instalar dependências, copiar um arquivo de ambiente,
  preparar um hook.
- Não cole nele um comando que você não entendeu, nem um que veio de uma mensagem de agente sem revisão.
- Se ele falhar, a worktree já foi criada — a falha é do comando, não da criação. Você pode rodar o
  comando de novo no terminal daquela pasta.

## Local ou em outra máquina

Quando o repositório mora em outra máquina, a worktree nasce **lá**: a criação é roteada pelo host do
repositório, e a pasta que você escolhe no diálogo é do outro lado. Como o comando pós-criação também
roda do outro lado, ele viaja pelo mesmo caminho — não é o seu computador que o executa.

## Limites e escopo

- **A lista não é um registro do Elyra.** Ela reflete o repositório; remover uma worktree pelo terminal
  tira o item da lista na próxima releitura, e uma worktree removida por fora pode aparecer como órfã.
- **Worktree não é workspace.** Nenhuma worktree é adotada como workspace automaticamente, e a lista não
  mostra quais pastas já são workspaces do app.
- **O nome da branch é validado pelo Git.** Branch inválida ou já em checkout em outra pasta é recusada
  pelo próprio Git, com a mensagem dele.
- **Uma worktree em uso não pode ser removida** pelo Git. Se a remoção falhar, confira se algum terminal
  está com aquela pasta aberta.
- **Criar worktree consome disco.** Cada checkout é uma cópia de trabalho dos arquivos rastreados.

## Ver também

- [Git no Elyra: o repositório é do projeto](/docs/pt-br/fluxos/git-conceito/)
- [Histórico de commits](/docs/pt-br/fluxos/git-historico/)