Saltar al contenido principal
Windsurf es compatible con el uso de worktrees de Git para ejecutar tareas de Cascade en paralelo sin interferir con tu workspace principal. Cuando usas worktrees, cada conversación de Cascade tiene su propia sesión, lo que permite que Cascade realice modificaciones o compile y pruebe código sin interferir con tu workspace principal.

​
Uso básico de worktrees

La forma más sencilla de empezar a usar worktrees es cambiar al modo “Worktree” en la esquina inferior derecha del campo de entrada de Cascade.
Actualmente, solo puedes cambiar a un worktree al comienzo de una sesión de Cascade. Las conversaciones no se pueden mover a un worktree diferente una vez iniciadas.
Después de que Cascade realice cambios en archivos dentro del worktree, tienes la opción de hacer clic en “merge” para incorporar esos cambios de nuevo en tu workspace principal.

​
Ubicación

Los worktrees se organizan por nombre de repositorio dentro de ~/.windsurf/worktrees/<repo_name>. A cada worktree se le asigna un nombre aleatorio único. Para ver una lista de worktrees activos, puedes ejecutar git worktree list desde el directorio del repositorio.
Debido a que los worktrees se encuentran en un directorio diferente al de tu proyecto original, los sistemas de compilación o las herramientas que dependen de rutas relativas (por ejemplo, referencias a ../shared-lib, dependencias enlazadas mediante enlaces simbólicos (symlinks) o dependencias de código fuente en un monorepo resueltas por ruta) pueden fallar dentro de un worktree. Si tu proyecto usa rutas relativas fuera de la raíz del repositorio, configura un hook post_setup_worktree para crear los enlaces simbólicos necesarios o copiar los archivos requeridos en las ubicaciones esperadas.

​
Hook de configuración

Cada worktree contiene una copia de los archivos de tu repositorio, pero no incluye archivos .env u otros paquetes que no estén bajo control de versiones. Si quieres incluir archivos o paquetes adicionales en cada worktree, puedes usar el hook post_setup_worktree para copiarlos en el directorio del worktree. El hook post_setup_worktree se ejecuta después de que cada worktree se haya creado y configurado. Se ejecuta dentro del nuevo directorio worktree. La variable de entorno $ROOT_WORKSPACE_PATH apunta a la ruta del workspace original y se puede usar para acceder a archivos o ejecutar comandos relativos al repositorio original.

​
Ejemplo

Copiar archivos de entorno e instalar dependencias al crear un nuevo worktree. Config (en .windsurf/hooks.json): 
{
  "hooks": {
    "post_setup_worktree": [
      {
        "command": "bash $ROOT_WORKSPACE_PATH/hooks/setup_worktree.sh",
        "show_output": true
      }
    ]
  }
}
Script (hooks/setup_worktree.sh): 
#!/bin/bash

# Copiar archivos de entorno desde el workspace original
if [ -f "$ROOT_WORKSPACE_PATH/.env" ]; then
    cp "$ROOT_WORKSPACE_PATH/.env" .env
    echo "Archivo .env copiado"
fi

if [ -f "$ROOT_WORKSPACE_PATH/.env.local" ]; then
    cp "$ROOT_WORKSPACE_PATH/.env.local" .env.local
    echo "Archivo .env.local copiado"
fi

# Instalar dependencias
if [ -f "package.json" ]; then
    npm install
    echo "Dependencias de npm instaladas"
fi

exit 0
Este hook garantiza que en cada worktree se instalen automáticamente la configuración de entorno y las dependencias necesarias.

​
Limpieza

Windsurf limpia automáticamente los worktrees más antiguos al crear un nuevo worktree para evitar un uso excesivo de disco. Cada workspace puede tener hasta 20 worktrees. Los worktrees se eliminan en función de la última vez que se accedió a ellos: los más antiguos se eliminan primero. Esta limpieza ocurre por workspace, lo que garantiza que los worktrees de diferentes repositorios permanezcan independientes entre sí. Además, si eliminas manualmente una conversación de Cascade, Windsurf eliminará automáticamente el worktree asociado.

​
Panel de control de código fuente

De forma predeterminada, Windsurf no muestra los worktrees creados por Cascade en el panel de SCM. Puedes establecer git.showWindsurfWorktrees en true en la configuración para anular este comportamiento y permitir visualizar los worktrees en el panel de SCM.