Git worktrees, explicados

Qué es un worktree

Un repositorio Git tiene un working tree: la carpeta con tus archivos, en checkout en una rama. git worktree agrega más. Cada worktree enlazado es otra carpeta, en su propia rama, que comparte el mismo repositorio: los mismos commits, ramas, tags, remotos y configuración.

No se copia ni se descarga nada. Un commit hecho en un worktree se ve al instante desde los demás, porque hay un solo .git. Lo que cada worktree tiene propio son sus archivos, su área de staging (índice) y su HEAD — la rama en la que está.

La carpeta que guarda el directorio .git es el worktree principal. En un worktree enlazado, .git es un archivo pequeño que apunta a la entrada de ese worktree dentro de .git/worktrees/ del principal. Por eso nunca debes borrar a mano la carpeta de un worktree enlazado: el repositorio seguiría guardando un registro de él (ver Problemas comunes).

Cuándo usarlo

• Un arreglo urgente en medio de una feature. Abre un worktree en main, arregla, commitea y haz push. Tu rama de feature queda tal como la dejaste — sin stash, sin un commit a medias.
• Revisar un pull request. Haz checkout de la rama en su propia carpeta, córrela con sus tests, mientras tu editor mantiene abierto tu trabajo.
• Builds o tests largos. Déjalos correr en un worktree mientras sigues programando en otro.
• Agentes de código en paralelo. Claude Code, Codex y Cursor le dan a cada tarea su propio worktree, así varios agentes (y tú) pueden trabajar en el mismo repositorio a la vez sin tocar los archivos de los demás.
• Comparar comportamiento. Corre la versión vieja y la nueva lado a lado.

Una regla define todo lo demás: una rama solo puede estar en checkout en un worktree a la vez. Git se niega a hacer checkout de una rama en la que ya está otro worktree, así dos carpetas nunca se pelean por la misma rama.

En la terminal

Todo lo que sigue es Git puro (2.17 o más nuevo para todo; Alfa Git igual necesita 2.30). Córrelo dentro del repositorio.

Crear un worktree

# una rama nueva, desde donde estás
git worktree add ../checkout-service-gift-cards -b feature/gift-cards

# una rama nueva desde otro punto (un tag, otra rama, un commit)
git worktree add ../checkout-service-hotfix -b hotfix/rounding v1.1.0

# una rama que ya existe
git worktree add ../checkout-service-review feature/refunds

El primer argumento es la carpeta nueva, normalmente junto al repositorio. Luego entra con cd y trabaja como siempre: git status, git commit y git push actúan sobre la rama de ese worktree.

Verlos

git worktree list
/home/tu/Projects/checkout-service                               d58320a [main]
/home/tu/Projects/checkout-service-hotfix                        9ac4877 [hotfix/rounding]
/home/tu/Projects/checkout-service/.claude/worktrees/refund-emails 79775bc [claude/refund-emails] locked

Borrar, bloquear y limpiar

# borra la carpeta y olvida el worktree (la rama se conserva)
git worktree remove ../checkout-service-hotfix

# se niega si hay cambios sin commitear; --force los descarta
git worktree remove --force ../checkout-service-hotfix

# protege un worktree de remove y prune (los agentes lo hacen)
git worktree lock --reason "sesión de agente" ../checkout-service-review
git worktree unlock ../checkout-service-review

# olvida los worktrees cuya carpeta se borró a mano
git worktree prune

Borrar un worktree nunca borra su rama, y sus commits siguen en el repositorio. Borra la rama aparte cuando ya no la necesites.

En Alfa Git

Alfa Git corre esos mismos comandos por ti y muestra cada worktree como un repositorio propio — con su estado, Changes, History y Review — anidado bajo el repositorio al que pertenece.

Encontrarlos

1. Abre tu carpeta de proyectos como workspace. Los worktrees aparecen bajo su repositorio en la sidebar, incluso los que están fuera de la carpeta, siempre que el repositorio mismo esté dentro. Haz clic en el contador junto al repositorio para plegarlos o desplegarlos.
2. Selecciona el repositorio principal y abre la pestaña Worktrees. Cada worktree es una tarjeta con su rama, su carpeta, sus cambios sin commitear, cuánto está adelante (↑) y atrás (↓) del worktree principal y su último commit. you are here marca el que tienes abierto; las etiquetas dicen si es el main, si está locked (bloqueado), si lo creó un agent o si su carpeta no existe (folder missing).
3. Abre la flecha de una tarjeta para ver sus archivos cambiados; haz clic en uno para ver su diff.

Crear uno

1. Haz clic en New Worktree en la pestaña Worktrees, o clic derecho sobre un repositorio en la sidebar y elige New Worktree….
2. Elige New branch (y desde dónde parte, Start from) o Existing branch. Las ramas que ya están en checkout en otro worktree aparecen, pero no se pueden elegir.
3. Revisa el nombre de la carpeta (Folder): se crea junto al worktree principal, y la ruta completa aparece debajo.
4. Deja marcado Open it when it is ready y haz clic en Create Worktree.

Trabajar entre worktrees

• Open cambia Alfa Git a ese worktree; Open in Editor y Open in Terminal (en el menú de la tarjeta) lo abren en tus propias herramientas.
• Compare abre Review con la rama del worktree contra la del principal: sus commits, cada archivo que cambia y si mergearla daría conflicto.
• En el History, una rama que otro worktree tiene en checkout lleva el icono de worktree (una chispa si es de un agente). Git no te dejaría hacer checkout de ella aquí, así que hacer doble clic — o Open worktree en su menú contextual — te lleva a ese worktree.

Borrar uno

Elige Remove Worktree… en el menú de la tarjeta, o clic derecho sobre el worktree en la sidebar. El sistema te pide confirmar. Si el worktree tiene cambios sin commitear, o está bloqueado (los agentes bloquean los suyos), el diálogo lo dice — con el motivo del bloqueo — y solo Remove Anyway lo borra. La rama siempre se conserva.

Si la carpeta de un worktree se borró fuera de la app, su tarjeta dice folder missing y Clean up corre git worktree prune para olvidarlo.

Worktrees creados por agentes de código

Claude Code, Codex y Cursor pueden trabajar cada tarea en su propio worktree, normalmente bajo .claude/worktrees/, .codex/worktrees/ o .cursor/worktrees/ — muchas veces fuera de la carpeta que abriste. Alfa Git los encuentra a través del repositorio al que pertenecen, así que no tienes que buscarlos:

• Aparecen bajo su repositorio con la etiqueta agent, y salen en Workspace Changes como cualquier otro repositorio.
• Los cambios que hace el agente aparecen solos, a medida que escribe archivos y hace commits.
• Antes de mergear el trabajo de un agente, usa Compare para revisar cada archivo, y ordena sus commits con un rebase interactivo (squash, fixup, reword) si quieres.
• Cuando la tarea termine, borra el worktree desde la app: te pregunta primero, porque los agentes bloquean sus worktrees mientras trabajan.

Problemas comunes

“is already checked out at” / “is already used by worktree at”

Esa rama está en checkout en otro worktree. Abre ese worktree (en Alfa Git, doble clic sobre la rama en el History), o crea una rama nueva a partir de ella.

Borré a mano la carpeta de un worktree

Git lo sigue listando, marcado como prunable. Corre git worktree prune, o haz clic en Clean up en la pestaña Worktrees. La rama y sus commits siguen ahí.

“cannot remove a locked working tree”

Alguien — normalmente un agente — lo bloqueó. Revisa con git worktree list que nada lo esté usando, luego desbloquéalo con git worktree unlock, o usa Remove Anyway en Alfa Git.

Mi stash aparece en todos los worktrees

Es lo esperado: el stash pertenece al repositorio, no a un worktree. Alfa Git muestra cada stash en el commit desde el que se hizo.

Resumen