Árboles de trabajo

En la aplicación de escritorio de ChatGPT, los árboles de trabajo permiten que Codex ejecute varios chats independientes en el mismo proyecto sin que interfieran entre sí. En los repositorios de Git, las tareas programadas pueden ejecutarse en árboles de trabajo en segundo plano dedicados para que no entren en conflicto con tu trabajo en curso. En los proyectos sin control de versiones, las tareas programadas se ejecutan directamente en el directorio del proyecto. También puedes iniciar chats manualmente en un árbol de trabajo y usar Handoff para mover un chat entre Local y Worktree.

Qué es un árbol de trabajo

Los árboles de trabajo solo funcionan en proyectos que forman parte de un repositorio de Git, ya que internamente utilizan árboles de trabajo de Git. Un árbol de trabajo te permite crear una segunda copia ("checkout") de tu repositorio. Cada árbol de trabajo tiene su propia copia de todos los archivos del repositorio, pero todos comparten los mismos metadatos (carpeta .git) sobre confirmaciones, ramas, etc. Esto te permite hacer checkout y trabajar en varias ramas en paralelo.

Terminología

• Checkout local: El repositorio que creaste. A veces se denomina simplemente Local en la aplicación de escritorio de ChatGPT.
• Worktree: Un árbol de trabajo de Git que se creó a partir de tu checkout local en la aplicación de escritorio de ChatGPT.
• Handoff: El flujo que mueve un chat entre Local y Worktree. Codex se encarga de las operaciones de Git necesarias para mover tu trabajo de forma segura entre ambos.

Por qué usar un árbol de trabajo

1. Trabaja en paralelo con Codex sin alterar tu configuración Local actual.
2. Pon en cola trabajo en segundo plano mientras mantienes la atención en el primer plano.
3. Mueve un chat a Local más adelante cuando quieras inspeccionar, probar o colaborar de forma más directa.

Primeros pasos

Los árboles de trabajo requieren un repositorio de Git. Asegúrate de que el proyecto seleccionado se encuentre en uno.

1. Selecciona "Worktree"

   En la vista de chat nuevo, selecciona Worktree debajo del cuadro de redacción. De manera opcional, elige un entorno local para ejecutar scripts de configuración para el árbol de trabajo.

2. Selecciona la rama inicial

   Debajo del cuadro de redacción, elige la rama de Git en la que se basará el árbol de trabajo. Puede ser tu rama main / master, una rama de funcionalidad o tu rama actual con cambios locales sin preparar.

3. Envía tu instrucción

   Envía tu instrucción y Codex creará un árbol de trabajo de Git basado en la rama que seleccionaste. De forma predeterminada, Codex trabaja en un "HEAD desacoplado".

4. Elige dónde continuar trabajando

   Cuando estés listo, puedes seguir trabajando directamente en el árbol de trabajo o transferir el chat a tu checkout local. Transferirlo hacia o desde Local mueve tanto el chat como el código para que puedas continuar en el otro checkout.

Trabajo entre Local y Worktree

Los árboles de trabajo tienen un aspecto y un funcionamiento muy similares a los de tu checkout local. La diferencia radica en el lugar que ocupan en tu flujo. Puedes considerar Local como el primer plano y Worktree como el segundo plano. Handoff te permite mover un chat entre ambos.

Internamente, Handoff gestiona las operaciones de Git necesarias para mover el trabajo de forma segura entre dos checkouts. Esto es importante porque Git solo permite que una rama esté en checkout en un lugar a la vez. Si haces checkout de una rama en un árbol de trabajo, no puedes hacer checkout de ella al mismo tiempo en tu checkout local, y viceversa.

En la práctica, hay dos rutas habituales:

1. Trabajar exclusivamente en el árbol de trabajo. Esta ruta funciona mejor cuando puedes verificar los cambios directamente en el árbol de trabajo, por ejemplo, porque instalaste dependencias y herramientas mediante un script de configuración del entorno local.
2. Transferir el chat a Local. Usa esta opción cuando quieras llevar el chat al primer plano, por ejemplo, porque quieres inspeccionar los cambios en tu IDE habitual o solo puedes ejecutar una instancia de tu aplicación.

Opción 1: Trabajar en el árbol de trabajo

Si quieres permanecer exclusivamente en el árbol de trabajo con tus cambios, convierte el árbol de trabajo en una rama mediante el botón Create branch here del encabezado del chat.

A partir de aquí, puedes confirmar tus cambios, enviar tu rama al repositorio remoto y abrir una solicitud de incorporación de cambios en GitHub.

Puedes abrir tu IDE en el árbol de trabajo mediante el botón "Open" del encabezado, usar la terminal integrada o cualquier otra herramienta que necesites utilizar desde el directorio del árbol de trabajo.

Recuerda que, si creas una rama en un árbol de trabajo, no puedes hacer checkout de ella en ningún otro árbol de trabajo, incluido tu checkout local.

Opción 2: Transferir un chat a Local

Si quieres llevar un chat al primer plano, selecciona Hand off en el encabezado del chat y muévelo a Local.

Esta ruta funciona bien cuando quieres leer los cambios en la ventana habitual de tu IDE, ejecutar tu servidor de desarrollo existente o validar el trabajo en el mismo entorno que ya usas a diario.

Codex gestiona los pasos de Git necesarios para mover el chat de forma segura entre el árbol de trabajo y tu checkout local.

Cada chat conserva el mismo árbol de trabajo asociado a lo largo del tiempo. Si más adelante vuelves a transferir el chat a un árbol de trabajo, Codex lo devuelve a ese mismo entorno en segundo plano para que puedas continuar donde lo dejaste.

También puedes hacerlo en la dirección opuesta. Si ya estás trabajando en Local y quieres liberar el primer plano, usa Hand off para mover el chat a un árbol de trabajo. Esto resulta útil cuando quieres que Codex siga trabajando en segundo plano mientras vuelves a centrar tu atención en otra tarea local.

Como Handoff utiliza operaciones de Git, los archivos que formen parte de tu archivo .gitignore no se moverán con el chat, a menos que Codex los copie en un árbol de trabajo local administrado con .worktreeinclude.

Detalles avanzados

Árboles de trabajo administrados por Codex y permanentes

De forma predeterminada, los chats utilizan un árbol de trabajo administrado por Codex. Están diseñados para ser ligeros y desechables. Por lo general, un árbol de trabajo administrado por Codex está dedicado a un chat, y Codex devuelve ese chat al mismo árbol de trabajo si más adelante vuelves a transferirlo allí.

Si quieres un entorno de larga duración, crea un árbol de trabajo permanente desde el menú de tres puntos de un proyecto en la barra lateral. Esto crea un nuevo árbol de trabajo permanente como proyecto independiente. Los árboles de trabajo permanentes no se eliminan automáticamente y puedes iniciar varios chats desde el mismo árbol de trabajo.

Cómo administra Codex los árboles de trabajo por ti

Codex crea árboles de trabajo en $CODEX_HOME/worktrees. La confirmación inicial es la confirmación HEAD de la rama seleccionada al iniciar la tarea. Si elegiste una rama con cambios locales, Codex también aplica los cambios no confirmados al árbol de trabajo. El árbol de trabajo no tiene una rama en checkout. Se encuentra en un estado de HEAD desacoplado. Esto permite que Codex cree varios árboles de trabajo sin llenar tus ramas de elementos innecesarios.

Copiar archivos locales ignorados en árboles de trabajo administrados

Los árboles de trabajo locales administrados por Codex parten de un checkout de Git, por lo que los archivos con seguimiento ya están presentes. Si tu repositorio ignora archivos de configuración local que necesita un árbol de trabajo nuevo, añade un archivo .worktreeinclude a la raíz del repositorio y enumera las rutas ignoradas o los patrones de estilo .gitignore que se copiarán cuando Codex cree un árbol de trabajo administrado.

Usa esta opción para archivos que Git ignora intencionalmente, como .env, .env.local o config/secrets.json. Codex solo copia los archivos ignorados que coinciden con .worktreeinclude; no copia otros archivos locales que Git no sigue. No enumeres archivos con seguimiento.

Codex copia automáticamente un archivo AGENTS.override.md ignorado en los árboles de trabajo locales administrados, por lo que no necesitas enumerarlo en .worktreeinclude.

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

Codex omite los enlaces simbólicos de origen y no sobrescribe archivos que ya existan en el checkout nuevo. Este comportamiento se aplica a los árboles de trabajo locales administrados por la aplicación de escritorio de ChatGPT, no a los árboles de trabajo remotos ni a los árboles de trabajo de Git que crees tú mismo desde la línea de comandos.

Limitaciones de las ramas

Supongamos que Codex termina un trabajo en un árbol de trabajo y decides crear en él una rama feature/a mediante Create branch here. Ahora quieres probarla en tu checkout local. Si intentaras hacer checkout de la rama, recibirías el siguiente error:

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

Para resolverlo, tendrías que hacer checkout de otra rama en lugar de feature/a en el árbol de trabajo.

Si planeas hacer checkout de la rama localmente, usa Handoff para mover el chat a Local en lugar de intentar mantener la misma rama en checkout en ambos lugares a la vez.

Limpieza de árboles de trabajo

Los árboles de trabajo pueden ocupar mucho espacio en disco. Cada uno tiene su propio conjunto de archivos del repositorio, dependencias, cachés de compilación, etc. Por ello, la aplicación de escritorio de ChatGPT intenta mantener la cantidad de árboles de trabajo dentro de un límite razonable.

De forma predeterminada, Codex conserva tus 15 árboles de trabajo administrados por Codex más recientes. Puedes cambiar este límite o desactivar la eliminación automática en la configuración si prefieres administrar personalmente el uso del disco.

Codex intenta evitar la eliminación de árboles de trabajo que todavía son importantes. Los árboles de trabajo administrados por Codex no se eliminarán automáticamente si:

• Hay un chat fijado vinculado a él
• El chat sigue en curso
• El árbol de trabajo es permanente

Los árboles de trabajo administrados por Codex se eliminan automáticamente cuando:

• Archivas el chat asociado
• Codex necesita eliminar árboles de trabajo más antiguos para mantenerse dentro del límite configurado

Antes de eliminar un árbol de trabajo administrado por Codex, Codex guarda una instantánea del trabajo que contiene. Si abres un chat después de que se haya eliminado su árbol de trabajo, verás la opción de restaurarlo.

Preguntas frecuentes