¿qué es un worktree de git?

el problema que resuelven los worktrees

Una carpeta solo puede tener una rama activa. Un worktree añade otra carpeta con otra rama.

Normalmente, un repo es una carpeta con una rama activa. Para trabajar en dos cosas a la vez, guardas tus cambios con stash, cambias de rama, haces el otro trabajo, vuelves y recuperas el stash. Funciona, pero es lento y fácil equivocarse.

Un worktree te da una segunda carpeta que ya está en otra rama. La función A vive en una carpeta y la función B en otra, las dos abiertas a la vez, sin stash ni cambios de rama.

por qué importa para los agentes de ia

Los worktrees son lo que hace seguro ejecutar varios agentes en un mismo repo.

Dos agentes de IA en la misma carpeta se sobrescriben entre sí. El agente A edita auth.ts, el agente B edita auth.ts un minuto después, y gana el que guarda el último. El trabajo del otro agente desaparece, y ninguno de los dos lo sabe.

Con un worktree para cada uno, cada agente tiene su propia carpeta, su propia rama y sus propios archivos. Los dos pueden editar auth.ts a la vez sin tocar la copia del otro. Cuando terminan, revisas y haces merge de cada rama por separado.

cómo se ve en el disco

Mismo historial, archivos separados. Dónde están las carpetas lo decides tú o tu herramienta.

my-project/                 ← your main checkout (main)
my-project/worktrees/
  ├─ add-auth/              ← worktree, branch add-auth
  └─ fix-nav/               ← worktree, branch fix-nav

Todos los worktrees comparten el mismo historial de git, así que un commit hecho en uno se ve desde los demás. Las ediciones sin commit se quedan en su propia carpeta. A git no le importa dónde estén los worktrees: junto al repo, en una carpeta aparte o dentro de él, como hace Pane.

cómo lo automatiza pane

Pane crea, llena y limpia un worktree para cada pane, así que nunca escribes los comandos.

No necesitas ejecutar ningún comando de git. Cuando creas un pane, Pane:

1. Toma un worktree que ha preparado de antemano para ese proyecto y esa rama, así que el pane se abre casi al instante, y le da una rama nueva.
2. Copia en él tus archivos .env, los ajustes de los agentes como .claude y .codex, y node_modules, para que el agente pueda empezar enseguida. Puedes cambiar la lista en Settings.
3. Cuando archivas el pane, comprueba si hay trabajo sin commit, sin seguimiento o sin push, y luego elimina el worktree. Puedes restaurar más tarde un pane archivado.

a mano

Tres comandos para crear y empezar, y dos para limpiar.

Sin una herramienta, lo mismo lleva unos cuantos comandos de git:

echo "worktrees/" >> .git/info/exclude   # once: keep them out of git status
git worktree add worktrees/add-auth -b add-auth
cd worktrees/add-auth
claude                      # start your agent here

# once the branch is merged:
git worktree remove worktrees/add-auth
git branch -d add-auth

Acuérdate de eliminar el worktree y borrar la rama cuando hayas hecho merge. La mayoría de la gente se olvida, y por eso las herramientas lo automatizan.

documentación relacionada

• → Panes y worktrees: cómo gestiona Pane los worktrees
• → Ejecutar agentes en paralelo: el flujo paralelo completo
• → Monorepos: worktrees en configuraciones monorepo
• → Worktrees de git para agentes de IA: resumen de la página

Fuentes

Correcciones

Si algo de lo que hay aquí es incorrecto o está desactualizado, avísanos y lo corregiremos y actualizaremos la fecha de arriba. Abre una incidencia en GitHub

Fuentes

• → git-worktree documentation
• → Panes & Worktrees (Pane docs)
• → Git worktree tools for AI agents