Worktrees

Los worktrees Git dan a las tareas paralelas archivos rastreados y ramas separadas en Paneflow. Cada checkout puede tener sus paneles y sesiones, mientras el historial del repositorio sigue compartido en tu máquina. Separar checkouts no elimina conflictos de fusión ni aísla programas.

Paneflow crea y elimina worktrees gestionados. Antes de eliminar uno, guarda un snapshot de los archivos sin commit del disco; guarda primero los buffers del editor. Los archivos ignorados y secretos locales requieren tratamiento separado, descrito más abajo.

Qué es un worktree

Los worktrees solo existen para proyectos que viven en un repositorio Git, porque Paneflow usa worktrees de Git por debajo. Un worktree es una segunda copia ("checkout") de tu repositorio. Tiene su propia copia de cada archivo, pero comparte los mismos metadatos (la carpeta .git) sobre commits, ramas y remotos. Eso es lo que permite hacer checkout y trabajar en varias ramas a la vez.

Terminología

• Checkout del proyecto: el repositorio que abriste como espacio de trabajo, al que apunta tu carpeta de proyecto.
• Worktree gestionado: un worktree Git que Paneflow creó desde ese checkout y que limpia por ti.
• Snapshot: un commit de los archivos sin commit del disco, justo antes de eliminar el worktree. Los buffers sin guardar y los archivos ignorados quedan fuera de esa garantía.

Por qué usar un worktree

• Deja que un agente trabaje en una funcionalidad mientras otro arregla un bug, cada uno en su rama, sin tocar el checkout del proyecto.
• Mantén una tarea larga en segundo plano mientras te concentras en el primer plano.
• Lee el diff en la pestaña Changes de la sesión, sin tocar el checkout de tu proyecto.

Primeros pasos

Los worktrees requieren un repositorio Git. Asegúrate de que el proyecto que abriste vive en uno.

Abrir un pane en una rama nueva

1. Añade un pane. La paleta "New pane" se abre con una fila de rama encima de la lista de agentes.
2. Abre la fila de rama y elige New branch….
3. Escribe un nombre de rama, o déjalo vacío para empezar en detached.
4. Elige en from la rama o el commit de partida. Por defecto es la rama en la que está tu proyecto.
5. Deja activado el interruptor Worktree.
6. Elige con qué abrir: un terminal, Claude Code, Codex, OpenCode o cualquier lanzador que hayas configurado.

Paneflow crea la rama y su worktree desde la base elegida, vincula la pestaña a ese worktree y abre el pane ahí. La pestaña muestra el nombre de la rama y el agente arranca dentro del directorio del worktree.

El mismo flujo existe en otros dos sitios:

• El menú contextual de la pestaña ofrece New branch… para una pestaña que ya existe.
• paneflow up y los flows aceptan los campos worktree y from; consulta Scripting.

Reutilizar una rama que ya existe

Elige una rama existente en la fila de rama, o escribe su nombre en "New branch…". Si la rama ya tiene checkout en un worktree, Paneflow reutiliza ese worktree. Si no tiene checkout en ningún sitio, Paneflow le crea un worktree. La base "from" se ignora en ese caso, porque la rama ya tiene su propio historial.

Git solo permite hacer checkout de una rama en un sitio a la vez. Paneflow nunca lucha contra esa regla: reutiliza el checkout existente en lugar de fallar con 'feature/a' is already used by worktree at ….

Empezar en detached y nombrar la rama después

Deja el nombre de rama vacío y Paneflow crea un worktree detached en la base elegida, llamado <base>-<sha> según el commit de partida. Es la opción correcta cuando aún no sabes si el trabajo merece una rama.

Cuando la merezca, haz clic derecho en la pestaña y elige Create branch here…. Paneflow ejecuta git switch -c dentro de ese worktree, así que tus cambios sin commit se quedan exactamente donde están.

Cambiar el checkout del proyecto en su lugar

Desactiva el interruptor Worktree en el formulario "New branch…" y Paneflow cambia tu checkout del proyecto a la rama, en el sitio, como haría git switch -c, en lugar de crear un worktree. El pane se abre en la raíz del repositorio y no se añade nada a la lista de gestionados.

Úsalo cuando trabajes solo en el repositorio y quieras una rama sin una segunda carpeta. Paneflow recuerda tu última elección en worktrees.for_new_branches, así que el interruptor se abre como lo dejaste.

Cambiar un checkout mueve los archivos bajo todos los panes que lo usan, así que Paneflow rechaza el cambio mientras un agente trabaje en ese checkout. Un worktree existe exactamente para ese caso.

Dónde viven los worktrees

Paneflow crea los worktrees gestionados bajo ~/.paneflow/worktrees (%USERPROFILE%\.paneflow\worktrees en Windows), un subdirectorio por repositorio y un directorio por rama:

~/.paneflow/worktrees/
  paneflow-05926cc4/
    feat-agents-browser/
    fix-login/

No se escribe nada dentro del propio checkout. La marca que le dice a Paneflow que un worktree es suyo vive en los metadatos Git del worktree, así que git status se mantiene limpio y la marca desaparece con el worktree.

Cambia la raíz en Settings > Worktrees, o define worktrees.dir en paneflow.json. La nueva raíz se aplica a los worktrees creados a partir de entonces; los creados bajo una raíz anterior siguen funcionando donde están y siguen listados.

Copiar archivos locales ignorados a los worktrees nuevos

Un worktree nuevo parte de un checkout Git, así que los archivos rastreados ya están. Los que Git ignora no, y un worktree suele necesitar unos cuantos para funcionar: .env, .env.local, un archivo local de secretos.

Añade un archivo .worktreeinclude en la raíz del repositorio y lista las rutas ignoradas a copiar, una por línea, relativas a la raíz. Los directorios también valen, con o sin / final, y # empieza un comentario.

# .worktreeinclude
.env
.env.local
config/secrets.json

Sin el archivo, Paneflow copia los .env* de primer nivel y AGENTS.override.md si existen. Un archivo que ya existe en el worktree nunca se sobrescribe. No listes archivos rastreados; Git ya los trae.

Limpieza

Los worktrees ocupan espacio: cada uno lleva sus propios archivos, dependencias y cachés de build. Paneflow mantiene su número razonable por sí solo.

Por defecto Paneflow conserva tus 15 worktrees gestionados más recientes. Cambia el límite o desactiva la eliminación automática en Settings > Worktrees, o con worktrees.keep_limit y worktrees.auto_remove en paneflow.json.

Un worktree gestionado se elimina automáticamente cuando:

• cierras el espacio de trabajo al que pertenece;
• Paneflow necesita recortar los más antiguos para no superar el límite de conservación.

Un worktree gestionado nunca se elimina automáticamente mientras una pestaña de un espacio de trabajo abierto lo use. La rama tampoco se borra nunca: eliminar un worktree solo elimina el checkout, tus commits siguen en la rama.

También puedes eliminar un worktree a mano desde Settings > Worktrees o desde el menú contextual de la pestaña. Paneflow solo elimina worktrees que creó él; los que hiciste tú con git worktree add se dejan en paz.

Snapshots

Antes de eliminar un worktree gestionado, automáticamente o a mano, Paneflow guarda su trabajo sin commit en un snapshot: ediciones de archivos rastreados, archivos nuevos y la rama en la que estaba el worktree. Un worktree limpio no deja snapshot.

Los snapshots son commits Git normales guardados bajo refs/paneflow/snapshots/ en tu repositorio. No tocan tus ramas, nunca se envían al remoto, y puedes inspeccionarlos con git log refs/paneflow/snapshots/<nombre> si quieres.

Settings > Worktrees los lista bajo "Snapshots":

• Restore recrea el worktree en su ruta original, en la misma rama, con los cambios guardados de vuelta como trabajo sin commit, y vuelve a copiar tus archivos de .worktreeinclude.
• Delete descarta el snapshot definitivamente.

Eliminar un worktree cuyos cambios ya no quieres es, a propósito, una operación en dos pasos: eliminar y luego borrar el snapshot.

Preguntas frecuentes

¿Puedo controlar dónde se crean los worktrees?

Sí. Define la raíz en Settings > Worktrees o con worktrees.dir. ~ se expande a tu directorio personal, y PANEFLOW_HOME mueve toda la carpeta ~/.paneflow, worktrees incluidos.

¿Qué pasa con mi trabajo cuando se elimina un worktree?

Tus commits siguen en la rama. Los cambios sin commit van a un snapshot que puedes restaurar desde Settings > Worktrees. Vuelve a elegir la rama en la paleta "New pane" para obtener un worktree nuevo desde su estado commiteado.

¿Puedo mover trabajo entre un worktree y el checkout de mi proyecto?

Haz commit o stash en el worktree y luego cambia el checkout del proyecto a la rama, desde el formulario "New branch…" con el interruptor Worktree desactivado o con git switch. Git se negará mientras la rama siga con checkout en el worktree, así que elimina antes ese worktree desde Settings > Worktrees.

¿Paneflow toca los worktrees que creé yo mismo?

No. Paneflow los lista en la fila de rama y abre panes en ellos, pero nunca elimina un worktree que no creó.

Dos tareas y después una integración

En Paneflow 0.17.4, empieza desde una base con commit en un proyecto Git desechable. Sigue New branch... con Worktree activado:

1. Crea feat/api-validation para la tarea y test/api-validation para los tests desde la misma base. Comprueba ruta y rama antes de cada agente.
2. Define qué archivos corresponden a cada tarea y usa puertos distintos. Instala dependencias en el checkout correspondiente. Los cambios sin commit del checkout principal no aparecen como archivos rastreados en el nuevo worktree; confirma primero la base necesaria.
3. Guarda, lee Changes frente al HEAD de cada checkout, confirma y revisa el diff completo de rama con Git. Changes no revisa desde el merge-base.
4. Integra los commits revisados en el checkout elegido, resuelve conflictos y ejecuta juntos los tests pertinentes. Conserva los checkouts mientras su trabajo útil no esté preservado.

Historial, remotos y referencias de rama son compartidos. Puertos, bases de datos, red y permisos no están aislados. .worktreeinclude puede copiar secretos locales; selecciona archivos por tarea. Un worktree no es un sandbox de seguridad.

Rama abierta, proyecto sin Git o edición sin guardar

Una rama ya extraída reutiliza su checkout existente; no crea otra copia independiente. Comprueba la ruta antes de asumir aislamiento. Un proyecto sin Git no tiene worktrees Git gestionados; usa su directorio o inicializa Git deliberadamente.

Guarda o descarta expresamente buffers antes de cambiar o eliminar el checkout. Los snapshots leen el disco, no texto sin guardar. Cambiar el checkout principal también se rechaza mientras un agente trabaja en él. Si Git rechaza el cambio por riesgo de sobrescritura, preserva archivos y resuelve la causa sin limpieza forzada.

Consulta Changes para el alcance de revisión y Files para conflictos de guardado.

Ver también

• Referencia de configuración: cada clave worktrees.*.
• Scripting: worktree y from en paneflow up.
• Ajustes: la página Worktrees.