Com as árvores de trabalho, o Codex pode executar vários chats independentes no mesmo projeto sem que um interfira no outro. O repositório e a árvore de trabalho ficam no computador ou no ambiente de desenvolvimento remoto onde está o projeto. É lá também que os comandos são executados. Você pode trabalhar diretamente no aplicativo ChatGPT para desktop ou usar o Codex no aplicativo ChatGPT para dispositivos móveis para iniciar chats em árvores de trabalho de um computador conectado, orientar o Codex, aprovar ações e revisar o trabalho.
Em repositórios Git, as tarefas agendadas podem ser executadas em segundo plano, em árvores de trabalho dedicadas, para evitar conflitos com o trabalho em andamento. Em projetos sem controle de versão, as tarefas agendadas são executadas diretamente no diretório do projeto. Você também pode iniciar chats manualmente em uma árvore de trabalho e usar a transferência para mover um chat entre Local e Árvore de trabalho.
As árvores de trabalho não são executadas no celular. O aplicativo ChatGPT para dispositivos móveis controla o Codex no computador conectado ou no ambiente de desenvolvimento remoto que esse computador usa. O repositório e a árvore de trabalho ficam onde o Codex é executado. Siga as instruções abaixo para desktop no computador conectado.
O que é uma árvore de trabalho?
As árvores de trabalho só funcionam em projetos que fazem parte de um repositório Git, pois usam as árvores de trabalho do Git. Com uma árvore de trabalho, você pode criar uma segunda cópia (“checkout”) do repositório. Cada árvore de trabalho tem sua própria cópia de todos os arquivos do repositório, mas todas compartilham os mesmos metadados (pasta .git) sobre commits, branches e outros elementos do Git. Assim, você pode fazer checkout de várias branches e trabalhar nelas em paralelo.
Terminologia
- Checkout local: o repositório que você criou. No aplicativo ChatGPT para desktop, ele às vezes aparece apenas como Local.
- Árvore de trabalho: uma árvore de trabalho do Git criada a partir do seu checkout local no aplicativo ChatGPT para desktop.
- Transferência: o processo de mover um chat entre Local e Árvore de trabalho. O Codex executa as operações do Git necessárias para mover seu trabalho com segurança de um ambiente para o outro.
Por que usar uma árvore de trabalho?
- Trabalhe em paralelo com o Codex sem interferir na configuração que você usa em Local.
- Coloque tarefas na fila para execução em segundo plano enquanto se concentra no trabalho em primeiro plano.
- Mova um chat para Local quando quiser examinar as alterações, fazer testes ou colaborar de forma mais direta.
Primeiros passos
As árvores de trabalho exigem um repositório Git. Verifique se o projeto selecionado faz parte de um.
-
Selecione “Árvore de trabalho”
Na tela de novo chat, selecione Árvore de trabalho abaixo do editor. Se quiser, escolha um ambiente local para executar os scripts de configuração da árvore de trabalho.
-
Selecione a branch inicial
Abaixo do editor, escolha a branch do Git que servirá de base para a árvore de trabalho. Você pode usar a branch
mainoumaster, uma branch de funcionalidade ou a branch atual com alterações locais que ainda não foram adicionadas à área de preparação. -
Envie seu prompt
Ao receber seu prompt, o Codex cria uma árvore de trabalho do Git com base na branch selecionada. Por padrão, o Codex trabalha com o HEAD desvinculado.
-
Escolha onde continuar o trabalho
Quando quiser, você pode continuar trabalhando diretamente na árvore de trabalho ou transferir o chat para o checkout local. A transferência de ou para Local move o chat e o código para que você possa continuar no outro checkout.
Como alternar entre Local e Árvore de trabalho
As árvores de trabalho são muito parecidas com o checkout local, tanto na aparência quanto no uso. A diferença está no papel de cada ambiente no seu fluxo de trabalho. Pense em Local como o ambiente em primeiro plano e em Árvore de trabalho como o ambiente em segundo plano. Com a transferência, você pode mover um chat entre eles.
Durante a transferência, o Codex executa as operações do Git necessárias para mover o trabalho com segurança entre dois checkouts. Isso é importante porque o Git só permite fazer checkout de uma branch em um lugar por vez. Se você fizer checkout de uma branch em uma árvore de trabalho, não poderá fazer checkout da mesma branch no checkout local ao mesmo tempo, e vice-versa.
Na prática, há duas opções comuns:
- Trabalhar exclusivamente na árvore de trabalho. Essa opção funciona melhor quando você consegue verificar as alterações diretamente na árvore de trabalho, por exemplo, se já instalou as dependências e ferramentas com um script de configuração do ambiente local.
- Transferir o chat para Local. Use essa opção quando quiser trazer o chat para o primeiro plano, por exemplo, para examinar as alterações no IDE que você costuma usar ou se só puder executar uma instância do aplicativo.
Opção 1: trabalhar na árvore de trabalho
Se quiser continuar trabalhando nas alterações exclusivamente na árvore de trabalho, use o botão Criar branch aqui no cabeçalho do chat para criar uma branch nessa árvore.
Depois, você pode fazer commit das alterações, enviar a branch para o repositório remoto e abrir um pull request no GitHub.
Use o botão “Abrir” no cabeçalho para abrir a árvore de trabalho no IDE. Você também pode usar o terminal integrado ou fazer o que mais precisar a partir do diretório da árvore de trabalho.
Lembre-se de que, ao criar uma branch em uma árvore de trabalho, você não poderá fazer checkout dela em outra árvore de trabalho, inclusive no checkout local, enquanto ela estiver em uso na primeira.
Opção 2: transferir um chat para Local
Para trazer um chat para o primeiro plano, selecione Transferir no cabeçalho do chat e mova-o para Local.
Essa opção funciona bem quando você quer examinar as alterações na janela do IDE que costuma usar, executar seu servidor de desenvolvimento ou validar o trabalho no mesmo ambiente que usa no dia a dia.
O Codex executa as operações do Git necessárias para mover o chat com segurança entre a árvore de trabalho e o checkout local.
Cada chat mantém o vínculo com a mesma árvore de trabalho. Se você transferir o chat de volta para uma árvore de trabalho, o Codex o levará ao mesmo ambiente em segundo plano para que você possa continuar de onde parou.
Você também pode fazer o caminho inverso. Se já estiver trabalhando em Local e quiser liberar o primeiro plano, use Transferir para mover o chat para uma árvore de trabalho. Assim, o Codex pode continuar trabalhando em segundo plano enquanto você volta a se dedicar a outra tarefa no ambiente local.
Como a transferência usa operações do Git, os arquivos ignorados pelo .gitignore não acompanham o chat, a menos que o Codex os copie para uma árvore de trabalho local gerenciada usando .worktreeinclude.
Detalhes avançados
Árvores de trabalho gerenciadas pelo Codex
Por padrão, os chats usam uma árvore de trabalho gerenciada pelo Codex. Essas árvores foram projetadas para serem leves e fáceis de descartar. Em geral, cada árvore de trabalho gerenciada pelo Codex é dedicada a um chat. Se você transferir o chat de volta, o Codex o levará à mesma árvore de trabalho.
Como o Codex gerencia suas árvores de trabalho
O Codex cria as árvores de trabalho em $CODEX_HOME/worktrees. O commit inicial é o commit HEAD da branch selecionada quando você inicia o chat. Se você escolher uma branch com alterações locais, o Codex também aplica à árvore de trabalho as alterações que ainda não entraram em um commit. O Codex não faz checkout de uma branch nessa árvore de trabalho. Ela fica com o HEAD desvinculado. Assim, o Codex pode criar várias árvores de trabalho sem acumular branches no repositório.
Como copiar arquivos locais ignorados para árvores de trabalho gerenciadas
As árvores de trabalho locais gerenciadas pelo Codex são criadas a partir de um checkout do Git, por isso já contêm os arquivos rastreados. Se o repositório ignora arquivos de configuração locais necessários para uma nova árvore de trabalho, adicione um arquivo .worktreeinclude à raiz do repositório. Nele, liste os caminhos ignorados ou use padrões no formato do .gitignore para indicar o que copiar quando o Codex criar uma árvore de trabalho gerenciada.
Use esse recurso para arquivos que o Git ignora intencionalmente, como .env, .env.local ou config/secrets.json. O Codex copia apenas os arquivos ignorados que correspondem às entradas de .worktreeinclude. Os demais arquivos locais que o Git não rastreia não são copiados. Não inclua arquivos rastreados na lista.
Se o Git ignorar o arquivo AGENTS.override.md, o Codex o copiará automaticamente para as árvores de trabalho locais gerenciadas. Você não precisa incluí-lo em .worktreeinclude.
# .worktreeinclude
.env
.env.local
config/secrets.jsonO Codex ignora links simbólicos na origem e não sobrescreve arquivos que já existem no novo checkout. Esse comportamento se aplica apenas às árvores de trabalho locais gerenciadas pelo aplicativo ChatGPT para desktop. As árvores de trabalho remotas e as que você cria com o Git pela linha de comando ficam fora desse escopo.
Limitações das branches
Suponha que o Codex termine uma tarefa em uma árvore de trabalho e você crie nela a branch feature/a usando Criar branch aqui. Agora você quer testá-la no checkout local. Se tentar fazer checkout da branch, verá o seguinte erro:
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'Para resolver o problema, faça checkout de outra branch na árvore de trabalho em que feature/a está em uso.
Se você pretende fazer checkout da branch localmente, use a transferência para mover o chat para Local em vez de tentar manter a mesma branch ativa nos dois lugares ao mesmo tempo.
Por que existe essa limitação?
O Git impede que a mesma branch fique ativa em mais de uma árvore de trabalho ao mesmo tempo porque cada branch representa uma única referência mutável (refs/heads/<name>) que indica “o estado atual do checkout” de uma árvore de trabalho.
Quando você faz checkout de uma branch, o Git trata o HEAD como pertencente àquela árvore de trabalho e espera que operações como git commit, git reset, git rebase e git merge atualizem essa referência uma de cada vez, em uma ordem bem definida. Se várias árvores de trabalho pudessem fazer checkout da mesma branch ao mesmo tempo, não ficaria claro qual delas deveria atualizar a referência da branch. Isso criaria condições de corrida e poderia causar perda de commits, inconsistências nos índices ou dúvidas sobre como resolver conflitos.
Ao limitar cada branch a uma árvore de trabalho por vez, o Git garante que cada branch tenha uma única cópia de trabalho de referência. Outras árvores de trabalho ainda podem referenciar os mesmos commits com segurança, usando um HEAD desvinculado ou branches distintas.
Limpeza das árvores de trabalho
As árvores de trabalho podem ocupar bastante espaço em disco. Cada uma tem seus próprios arquivos do repositório, dependências, caches de compilação e outros arquivos. Por isso, o aplicativo ChatGPT para desktop procura limitar o número de árvores de trabalho.
Por padrão, o Codex mantém as 15 árvores de trabalho mais recentes que ele gerencia. Se preferir gerenciar o uso do disco por conta própria, você pode alterar esse limite ou desativar a exclusão automática nas configurações.
O Codex procura evitar a exclusão de árvores de trabalho que ainda sejam importantes. Uma árvore de trabalho gerenciada pelo Codex fica protegida contra exclusão automática quando:
- Há um chat fixado vinculado a ela
- O chat ainda está em andamento
As árvores de trabalho permanentes criadas em versões anteriores continuam disponíveis e protegidas contra a limpeza automática. A opção de criar árvores de trabalho permanentes não está mais disponível no menu do projeto.
O Codex exclui automaticamente uma árvore de trabalho que gerencia quando:
- Você arquiva o chat associado
- O Codex precisa excluir árvores de trabalho mais antigas para respeitar o limite configurado
Antes de excluir uma árvore de trabalho que gerencia, o Codex salva uma cópia do trabalho no estado em que ele se encontra. Se você abrir o chat depois que a árvore de trabalho for excluída, verá a opção de restaurá-la.
Perguntas frequentes
Posso escolher onde criar as árvores de trabalho?
Sim. Por padrão, o Codex cria as árvores de trabalho gerenciadas em $CODEX_HOME/worktrees. Para escolher outro local, abra Configurações > Árvores de trabalho e altere Raiz das árvores de trabalho.
Posso mover um chat entre Local e Árvore de trabalho?
Sim. Use Transferir no cabeçalho do chat para movê-lo entre o checkout local e uma árvore de trabalho. O Codex executa as operações do Git necessárias para mover o chat com segurança entre os ambientes. Se você transferir o chat de volta para uma árvore de trabalho, o Codex o levará à mesma árvore de trabalho associada a ele.
O que acontece com os chats se uma árvore de trabalho for excluída?
Os chats podem continuar no histórico mesmo após a exclusão do diretório da árvore de trabalho. No caso das árvores de trabalho gerenciadas pelo Codex, ele salva uma cópia do trabalho antes de excluir a árvore e oferece a opção de restaurá-la se você reabrir o chat associado.