Git worktree: add, list, remove y prune, con ejemplos | We.Inc
Genera el comando git worktree add exacto para una rama nueva, una rama existente o un commit suelto, y luego lista, bloquea, mueve, elimina y limpia worktrees con seguridad.
git worktree permite que un repositorio tenga varias carpetas de trabajo, cada una en su propia rama, compartiendo un único almacén de objetos. Ejecuta git worktree add ../hotfix -b hotfix para crear una carpeta nueva en una rama nueva, git worktree list para verlas todas y git worktree remove ../hotfix al terminar. No hace falta un segundo clon.
Los comandos de worktree que necesitas a diario
Tarea
Comando
Carpeta nueva en una rama nueva
git worktree add ../app-fix -b fix/login
Carpeta nueva en una rama existente
git worktree add ../app-review feature/cart
Carpeta desechable en un commit
git worktree add --detach ../app-old v1.4.0
Ver todos los worktrees
git worktree list
Eliminar un worktree
git worktree remove ../app-fix
Limpiar carpetas que borraste a mano
git worktree prune
Hacer stash, cambiar de rama y recompilar cada vez que alguien pide un arreglo rápido es perder el tiempo. Un worktree te da una segunda copia de trabajo del mismo repo en otra carpeta, así una batería de tests larga, una revisión de código y un parche urgente pueden vivir cada uno en su propio directorio. Usa el generador para obtener los comandos y consulta la referencia para los subcomandos menos habituales.
Escribe la carpeta que quieres y el nombre de la rama, y elige rama nueva, rama existente o commit suelto.
Copia el comando add y ejecútalo desde dentro de tu copia de trabajo principal.
Trabaja en la carpeta nueva como en cualquier clon: haz commit, push y pull desde ahí.
Cuando la rama esté fusionada, ejecuta el comando remove que muestra el generador, y prune si alguna vez borraste una carpeta a mano.
Mantén los worktrees como carpetas hermanas, por ejemplo ../app-fix, para que nunca queden dentro del árbol de la copia principal.
Cada worktree necesita sus propias dependencias instaladas y su propia salida de build. Reserva espacio en disco para node_modules en cada carpeta.
Una rama solo puede estar abierta en un worktree a la vez. Si add se niega, mira en git worktree list dónde está ya abierta.
Bloquea un worktree que esté en una unidad extraíble con git worktree lock --reason "usb disk" para que prune no lo borre mientras está desconectada.
Preguntas frecuentes
¿Qué diferencia hay entre un worktree y un clon?
Un clon copia el repositorio entero, historial incluido. Un worktree enlazado comparte los objetos y las refs del repositorio original y solo añade una carpeta de trabajo nueva y algo de metadatos, así que los commits hechos en uno se ven al instante desde los demás sin hacer fetch.
¿Pueden dos worktrees usar la misma rama?
No por defecto. git worktree add rechaza una rama que ya está abierta en otro sitio, porque dos carpetas moviendo la misma rama se pisarían el trabajo. --force lo permite, pero un HEAD desacoplado o una segunda rama es casi siempre mejor opción.
¿Por qué falla git worktree remove?
Se niega cuando la carpeta tiene archivos versionados modificados o archivos sin versionar, para que no pierdas trabajo. Haz commit o limpia la carpeta antes, o pasa --force. Un worktree bloqueado necesita --force dos veces.
¿Qué hace git worktree prune?
Borra los registros sobrantes que git guarda de worktrees cuyas carpetas ya no existen, por ejemplo después de eliminar una con rm -rf. Añade -n para ver antes qué eliminaría.
¿Cómo renombro o muevo la carpeta de un worktree?
Usa git worktree move <worktree> <new-path> para que git actualice sus registros. Si ya la moviste con el explorador de archivos, ejecuta git worktree repair desde la nueva ubicación para reconectarla.
Buenos motivos para usar worktrees
Revisar un pull request sin tocar trabajo a medias, dejar una suite de tests lenta corriendo en una rama mientras programas en otra y comparar dos versiones de una app lado a lado son los casos clásicos.
También encajan con herramientas que ejecutan varias sesiones de programación sobre un mismo repositorio: cada sesión tiene su propia carpeta y rama, así los archivos sin commit de una sesión nunca se cuelan en el build de otra.
Qué se comparte y qué no
Todos los worktrees comparten commits, ramas, tags, remotos y casi toda la configuración. Cada uno tiene su propio HEAD, índice y archivos de trabajo, así que preparar cambios en una carpeta no afecta a las demás.
Los archivos ignorados como .env, node_modules y las carpetas de build no se copian a un worktree nuevo. Copia tú el archivo env e instala las dependencias antes de ejecutar nada.