Gestiona los worktrees de Git de tu ordenador desde el móvil
Una guía práctica para añadir, cambiar y limpiar worktrees de Git en remoto, con un flujo móvil para revisar, hacer cambios pequeños y commits seguros.
- CLI
- 0.2.17
- Ref de preview
- a2c45c8
Los worktrees de Git pueden parecer una función avanzada para gente "seria" con Git.
Pero la misma situación se repite una y otra vez:
- estás en mitad de un cambio
- aparece un hotfix pequeño
- o necesitas revisar otra rama rápidamente
- y no quieres andar con stash/unstash
Los worktrees resultan ser una respuesta limpia.
La segunda conclusión fue más práctica:
si puedes gestionar worktrees desde el móvil, dejas de bloquearte con "ya lo haré cuando vuelva a mi mesa".
Esta guía es un flujo tranquilo y repetible para worktrees, con el móvil como panel de control.
Definición rápida: qué es un worktree (en lenguaje llano)
Un repositorio Git normalmente tiene un directorio de trabajo (tus archivos en checkout).
Un worktree permite que un repositorio tenga varios directorios de trabajo, así que puedes tener más de una rama en checkout a la vez.
La documentación de Git lo describe como gestionar "varios árboles de trabajo vinculados al mismo repositorio", lo que te permite tener más de una rama en checkout a la vez. (Fuente: https://git-scm.com/docs/git-worktree)
En la práctica:
- la base de datos de objetos del repositorio es compartida
- cada worktree tiene sus propios archivos en checkout y su propio estado de index/HEAD
Por eso los worktrees resultan mucho más ligeros que "clonar el repositorio dos veces".
Enfoques habituales y sus contrapartidas
Cuando un hotfix interrumpe un cambio más grande, las opciones habituales son:
- stash: funciona, pero es fácil olvidar qué guardaste y por qué
- hacer commit de un WIP: funciona, pero ensucia el historial e invita a errores
- clonar otra vez: funciona, pero es lento y duplica mucho
Los worktrees te permiten mantener limpia la rama principal y no perder el ritmo.
Un flujo que funciona
Este flujo usa una interfaz remota sobre el ordenador que tiene el repositorio para el control diario de Git.
Happier es una opción compatible con ese enfoque.
Cada sesión de Happier está vinculada a una carpeta de tu ordenador y, en el móvil, la sesión da a esa carpeta sus propias pestañas Archivos (Files) y Git. Así que una carpeta de worktree más una sesión dentro es todo lo que necesitas.
Las acciones de escritura de Git (commit, traer, enviar, cambiar de rama) son experimentales y están desactivadas por defecto. Se activan en Configuración (Settings) → Características (Features) → Operaciones de control de versiones (Source control operations) (consulta la documentación de Git (en inglés)). Ver el estado y los diffs funciona sin eso.
Contrapartida: tu ordenador tiene que estar en línea.
Si Happier es nuevo para ti (qué es y dónde conseguirlo)
Si no conocías Happier: es una app complementaria de código abierto (móvil/web/escritorio) que te permite mantener tus flujos en un ordenador de confianza y gestionarlos desde el móvil.
Para empezar:
- Cómo usar Happier desde el móvil
- GitHub: https://github.com/happier-dev/happier
- Instalación/descarga: https://github.com/happier-dev/happier#how-it-works
- Discord (comunidad y soporte): https://discord.gg/W6Pb8KuHfg
El modelo mental que evita errores
Antes de tocar worktrees desde el móvil, adopta dos reglas:
-
Un worktree = una intención. Si el hotfix no tiene relación, merece su propio worktree.
-
Cambios pequeños desde el móvil, cirugía profunda con teclado. El móvil va muy bien para revisar, hacer cambios ligeros y enviar un arreglo acotado.
Paso a paso: gestiona worktrees desde el móvil
1) Abre una sesión en la carpeta del repositorio
Abre una sesión que se ejecute en el repositorio, o inicia una nueva y elige la carpeta del repositorio en tu ordenador como directorio de trabajo.
2) Usa la pestaña Git como tu "vista de seguridad"
Dentro de la sesión:
- abre la pestaña Git
- empieza por los archivos cambiados
Esto te da una forma limpia de:
- revisar qué hay modificado
- hacer commit de forma intencionada
- sincronizar (Traer/Enviar)
Si ves:
- Operation requires a clean working tree. (la operación requiere un árbol de trabajo limpio)
…tómalo como una barandilla de seguridad.
3) Crea un worktree nuevo (hotfix)
Hay dos formas de pensar en crear un worktree:
- "quiero un directorio nuevo para una rama nueva"
- "quiero un directorio nuevo para una rama existente"
En Git puro, eso es básicamente:
git worktree add <path>(atajo para rama nueva)- o
git worktree add <path> <branch>(rama existente)
(Fuente: https://git-scm.com/docs/git-worktree)
En Happier, lo que importa es el resultado:
- un segundo directorio de trabajo en el que puedes iniciar su propia sesión
- sin alterar lo que ya estaba en checkout
4) Mantén acotados los cambios desde el móvil
Una vez que existe el worktree, el ciclo en el móvil es:
- abre la sesión que se ejecuta en el worktree
- usa Archivos para buscar el archivo exacto
- haz el cambio mínimo
- Guardar (Save)
- cambia a la pestaña Git y revisa el diff
- selecciona exactamente los archivos que forman parte del arreglo (disponible desde la 0.2.12) y haz commit de un cambio pequeño
5) Envía el hotfix (y para)
Una vez enviado el hotfix, para.
El valor de los worktrees es que el hotfix no se convierte en un segundo proyecto entero.
Se mantiene acotado.
6) Limpia los worktrees (para que no se acumulen)
Los worktrees son potentes, pero se acumulan.
Una buena regla:
- si la rama está fusionada, elimina el worktree
- si es de larga duración, mantenlo pero ponle un nombre claro
En Git puro, los archivos administrativos obsoletos se pueden limpiar con git worktree prune si un worktree se borró de forma incorrecta. (Fuente: https://git-scm.com/docs/git-worktree)
En un flujo centrado en la interfaz, el objetivo es más sencillo: no dejar un montón de directorios de trabajo abandonados.
Worktrees + varios agentes (por qué esto empezó a importar)
Los worktrees existen desde hace tiempo, pero se vuelven mucho más útiles cuando ejecutas más de un agente o sesión en paralelo.
Si usas Claude Code, Codex u OpenCode, el patrón básico con varios agentes es este:
- un worktree por tarea
- una sesión por worktree
Eso te da aislamiento:
- los agentes no se pisan los archivos
- los diffs son más fáciles de revisar
- los commits se mantienen acotados
En Happier puedes hacerlo sin convertir el móvil en una terminal:
- crea un worktree
- lanza una sesión nueva en esa carpeta de worktree (Claude/Codex/OpenCode)
- sigue las sesiones desde la misma app donde también revisas diffs, commits e historial
Esto no va, a propósito, de "ejecutar 10 agentes a la vez".
Va de ejecutar 2 o 3 en paralelo y mantenerlos aislados para que la revisión siga siendo manejable.
Terminal (opcional)
Las sesiones pueden mostrar una pestaña Terminal (CLI) (Terminal) cuando la terminal integrada está disponible. Es experimental según la matriz de funciones (en inglés) y necesita un daemon conectado y una máquina accesible.
Trata la terminal como la salida de emergencia para:
- ese comando que la interfaz no ofrece
- comprobaciones rápidas
- limpiar worktrees cuando algo está en un estado raro
Si te encuentras haciéndolo todo en la terminal, es una señal para:
- simplificar el flujo, o
- esperar a tener teclado
Preguntas frecuentes (dudas reales sobre worktrees)
¿Qué diferencia hay entre una rama y un worktree?
Una rama es un puntero (un nombre para una línea de commits).
Un worktree es un directorio de trabajo separado donde puedes hacer checkout de una rama.
Normalmente se usan juntos: una rama por worktree.
¿Por qué usar worktrees en lugar de stash?
El stash va muy bien para cambios de contexto rápidos.
Los worktrees van muy bien cuando la interrupción es trabajo real (un hotfix, una revisión, una ejecución de pruebas) y no quieres ninguna posibilidad de pisar tus cambios actuales.
¿Puedo tener la misma rama en checkout en dos worktrees?
Por defecto, Git impide tener la misma rama en checkout en dos worktrees a la vez.
Es una medida de seguridad.
(Puedes usar worktrees con HEAD separado para trabajos del tipo "solo ejecutar pruebas" sin rama.)
¿Cómo nombro los worktrees para que mi yo futuro los entienda?
Usa nombres que expresen la intención:
hotfix-<ticket>review-<pr>release-<version>
¿Cuál es un fallo grave típico con los worktrees?
No es la parte de Git.
Es la parte humana:
- olvidar qué worktree es "el que tiene cambios sin enviar"
- dejar por ahí worktrees de hotfix a medio terminar
La solución es sencilla: mantén los worktrees acotados y límpialos.
¿Cuándo no debería usar worktrees desde el móvil?
Si vas a:
- resolver conflictos
- hacer un rebase interactivo
- hacer refactorizaciones grandes
Eso conviene hacerlo con teclado.
¿Qué significa "worktree is locked"?
Git te permite bloquear un worktree para que no se limpie automáticamente con prune.
Es útil si el worktree está en un disco o ubicación que no siempre está montado.
¿Qué hace "prune" y cuándo lo necesito?
Si una carpeta de worktree se borra de forma incorrecta (sin git worktree remove), Git puede quedarse con metadatos obsoletos.
git worktree prune limpia esos archivos administrativos obsoletos.
Si nunca borras carpetas de worktree a mano, rara vez lo necesitarás.
¿Puedo usar worktrees para mantener separadas ramas de larga duración (no solo hotfixes)?
Sí, es un buen uso.
Ejemplos:
- mantener
mainlimpia en el worktree principal - tener
release/<version>en un worktree dedicado - tener una refactorización larga en su propio worktree
Reduce los cambios de contexto y facilita las revisiones rápidas.
¿Los worktrees comparten node_modules o artefactos de build?
No automáticamente.
Cada worktree es un directorio separado, así que la mayoría de las herramientas lo tratan como una carpeta de proyecto distinta.
Si quieres cachés compartidas, normalmente se encarga la capa del lenguaje o de las herramientas (pnpm store, caché de Gradle, etc.), no Git.
¿Dónde debería poner las carpetas de worktree?
Junto a la carpeta principal del repositorio, con nombres claros.
Por ejemplo:
repo/(worktree principal)repo--hotfix-123/repo--release-1.2/
Un buen esquema de nombres es el que deja claro, desde la pantalla del móvil, qué estás mirando.
¿Puedo eliminar un worktree de forma segura desde el móvil?
Sí, pero sigue antes una regla de seguridad:
- asegúrate de que no tiene cambios sin commit
- ni commits sin enviar que todavía te importen
Revisar rápidamente los "Archivos modificados" (Changed files) antes de eliminarlo es un seguro barato.
¿git worktree es lo mismo que git switch / git checkout?
No.
switch/checkoutcambia la rama a la que apunta un único directorio de trabajo.worktree addcrea un segundo directorio de trabajo para que no tengas que cambiar.
¿Debería usar worktrees en lugar de ramas?
No. Los worktrees complementan a las ramas.
Un buen valor por defecto sigue siendo:
- una rama por worktree
¿Puedo usar worktrees con submódulos?
Sí, pero con cuidado: cada worktree tiene su propio estado de checkout.
Si los submódulos forman parte de tu flujo, mantén acotados los cambios desde el móvil y deja la "cirugía de submódulos" más profunda para el teclado.