Los worktrees te permiten ejecutar varios agentes en el mismo proyecto sin
que se pisen entre sí. Cada uno recibe su propio checkout del repositorio,
en su propia rama, con sus propios panes y sesiones de agente, mientras el
repositorio, los worktrees y los comandos se quedan en tu máquina.
Paneflow crea y elimina estos worktrees por ti. Antes de eliminar uno,
guarda el trabajo sin commit en un snapshot que puedes restaurar después.
## 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 que Paneflow hace con los cambios sin commit de un
worktree justo antes de eliminarlo, para que no se pierda nada.
### 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 resultado después en [Review](/docs/review), junto a otros
worktrees, sin hacer checkout de nada.
## 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 tres sitios:
- El **Launch Pad** tiene un campo "New branch" y el mismo selector "From".
- 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](/docs/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 `-` 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:
```text
~/.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.
```text
# .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/` 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.
## Worktrees y Review
[Review](/docs/review) lee los worktrees sin hacer checkout de nada.
Arrastra una rama o un worktree al borde de un pane para leer su diff
contra la base que elijas, hasta seis en paralelo. Eliminar un worktree lo
quita también de Review.
## 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ó.
## Ver también
- [Referencia de configuración](/docs/configuration/schema#worktrees): cada
clave `worktrees.*`.
- [Review](/docs/review): leer diffs de worktrees en paralelo.
- [Scripting](/docs/scripting): `worktree` y `from` en `paneflow up`.
- [Ajustes](/docs/settings): la página Worktrees.
