git worktree

Qué hace git worktree

El comando git worktree te permite extraer más de una rama al mismo tiempo desde un único repositorio. Cada worktree es un directorio de trabajo independiente con su propia rama extraída y su propio índice, pero todos comparten el mismo almacén de objetos .git, el historial, las referencias y la configuración. Es la forma limpia de trabajar en dos ramas en paralelo sin necesidad de clonar el repositorio dos veces.

El directorio al que clonaste es tu worktree principal; cada directorio que creas con git worktree add es un worktree vinculado. Los worktrees vinculados son ligeros: almacenan solo un pequeño archivo .git (no una carpeta) que apunta de regreso al repositorio compartido, por lo que ocupan casi nada en disco en comparación con un segundo clon.

Esta página explica cuándo usar un worktree, cómo agregar, listar, mover y eliminar worktrees, las reglas que Git impone y los errores más comunes.

El problema que resuelve

Imagina que estás inmerso en una rama de características cuando llega un informe de error urgente. Normalmente tendrías que guardar tu trabajo temporalmente, cambiar de rama, corregir el error, volver a cambiar y restaurar el trabajo guardado — algo disruptivo y propenso a errores. Con los worktrees, simplemente creas un segundo directorio de trabajo apuntando a la rama de corrección urgente, arreglas el error allí y dejas tu trabajo en la característica completamente intacto. Cuando la compilación necesita los dos estados en paralelo — por ejemplo, para comparar comportamientos o ejecutar dos suites de pruebas largas al mismo tiempo — los worktrees destacan donde el guardado temporal no puede ayudar.

Agregar un worktree

Apunta git worktree add a una ruta y a una rama. Para extraer una rama existente en un directorio hermano:

git worktree add ../hotfix hotfix

Esto crea ../hotfix con la rama hotfix extraída:

Preparing worktree (checking out 'hotfix')
HEAD is now at 1a2b3c4 Add login form

Para crear una rama completamente nueva al mismo tiempo, usa -b. El último argumento es el punto de inicio en el que se basa la nueva rama:

git worktree add -b experiment ../experiment main

Ahora tienes dos directorios de trabajo independientes respaldados por un solo repositorio. Si omites la rama por completo, Git crea una rama con el nombre del componente final de la ruta:

git worktree add ../docs    # creates and checks out a branch named "docs"

Para inspeccionar un commit sin asignarle una rama — útil para probar una versión antigua — agrégalo en estado HEAD desconectado:

git worktree add --detach ../v1-check v1.0.0

Consulta Detached HEAD para entender qué significa ese estado.

Listar worktrees

Consulta todos los árboles de trabajo vinculados al repositorio:

git worktree list

La salida muestra cada ruta, el commit en el que se encuentra y la rama (o (detached HEAD)):

/home/dev/project          1a2b3c4 [main]
/home/dev/hotfix           9f8e7d6 [hotfix]
/home/dev/v1-check         0011223 (detached HEAD)

Agrega --porcelain para obtener un formato estable y compatible con scripts.

Mover y eliminar worktrees

Para reubicar un worktree vinculado, deja que Git actualice sus registros internos en lugar de usar mv de la shell:

git worktree move ../hotfix ../urgent-fix

Cuando termines con uno, elimínalo (esto borra su directorio):

git worktree remove ../urgent-fix

Git se niega a eliminar un worktree que tiene cambios sin confirmar o archivos sin seguimiento, por lo que no perderás trabajo por accidente. Cuando estés seguro, anula esa comprobación con --force:

git worktree remove --force ../urgent-fix

Si eliminaste manualmente la carpeta de un worktree con rm -rf, el repositorio sigue conservando un registro administrativo obsoleto. Límpialo con:

git worktree prune

Bloquear un worktree

Si un worktree reside en una unidad extraíble o en una unidad de red, bloquéalo para que prune no elimine su registro mientras la unidad está desmontada:

git worktree lock ../usb-backup --reason "external disk"
git worktree unlock ../usb-backup

Resumen de comandos

Reglas y errores comunes

• Una rama, un worktree. Una rama solo puede estar extraída en un worktree a la vez. Si intentas agregar un worktree para una rama que ya está extraída en otro lugar, Git rechaza la operación con fatal: '<branch>' is already used by worktree at .... Esto garantiza que dos directorios nunca puedan competir por el mismo puntero de rama. Usa --detach, o una nueva rama con -b, si necesitas el mismo commit en dos lugares.
• Los cambios locales no se comparten. Cada worktree tiene sus propios archivos de trabajo, índice y stash. Los commits, ramas, etiquetas y remotos sí se comparten porque residen en el almacén común .git.
• Eliminar el worktree principal. No puedes ejecutar git worktree remove sobre el worktree original (principal) — solo sobre los vinculados.
• Los repositorios bare son un excelente host para los worktrees: clona con git clone --bare, luego agrega cada rama de trabajo como su propio worktree, manteniendo los datos del repositorio separados de cualquier extracción.

Comandos relacionados

• git branch — crea y gestiona las ramas que extraes en los worktrees.
• git switch — cambia entre ramas dentro de un único directorio de trabajo.
• git stash — la alternativa más antigua de un solo directorio para un worktree rápido.

Práctica