Árvores de trabalho
Utilize árvores de trabalho no Codex, na aplicação ChatGPT para computador, para executar conversas em paralelo
Na aplicação ChatGPT para computador, as árvores de trabalho permitem ao Codex executar várias conversas independentes no mesmo projeto sem que interfiram entre si. Nos repositórios Git, as tarefas agendadas podem ser executadas em árvores de trabalho dedicadas em segundo plano, para não entrarem em conflito com o trabalho em curso. Em projetos sem controlo de versões, as tarefas agendadas são executadas diretamente no diretório do projeto. Também pode iniciar manualmente conversas numa árvore de trabalho e utilizar o Handoff para mover uma conversa entre Local e Worktree.
O que é uma árvore de trabalho
As árvores de trabalho só funcionam em projetos que façam parte de um repositório Git, uma vez que utilizam árvores de trabalho do Git nos bastidores. Uma árvore de trabalho permite criar uma segunda cópia ("checkout") do seu repositório. Cada árvore de trabalho tem a sua própria cópia de todos os ficheiros do repositório, mas todas partilham os mesmos metadados (pasta .git) relativos a commits, branches, entre outros. Isto permite fazer checkout e trabalhar em várias branches em paralelo.
Terminologia
- Checkout local: o repositório que criou. Por vezes, é referido simplesmente como Local na aplicação ChatGPT para computador.
- Árvore de trabalho: uma árvore de trabalho do Git criada a partir do seu checkout local na aplicação ChatGPT para computador.
- Handoff: o fluxo que move uma conversa entre Local e Worktree. O Codex trata das operações do Git necessárias para mover o seu trabalho entre ambos em segurança.
Porquê utilizar uma árvore de trabalho
- Trabalhe em paralelo com o Codex sem alterar a configuração Local atual.
- Coloque trabalho em fila de espera para ser executado em segundo plano enquanto mantém a atenção no primeiro plano.
- Mova posteriormente uma conversa para Local quando estiver pronto para inspecionar, testar ou colaborar de forma mais direta.
Primeiros passos
As árvores de trabalho requerem um repositório Git. Certifique-se de que o projeto selecionado se encontra num repositório.
Selecione "Worktree"
Na vista de nova conversa, selecione Worktree por baixo da caixa de composição. Opcionalmente, escolha um ambiente local para executar scripts de configuração para a árvore de trabalho.
Selecione a branch inicial
Por baixo da caixa de composição, escolha a branch do Git na qual pretende basear a árvore de trabalho. Pode ser a sua branch
main/master, uma branch de funcionalidade ou a sua branch atual com alterações locais não preparadas.Envie o seu pedido
Envie o seu pedido e o Codex cria uma árvore de trabalho do Git baseada na branch selecionada. Por predefinição, o Codex trabalha num "detached HEAD".
Escolha onde continuar a trabalhar
Quando estiver pronto, pode continuar a trabalhar diretamente na árvore de trabalho ou transferir a conversa para o seu checkout local. O Handoff de ou para Local move a sua conversa e o código, para que possa continuar no outro checkout.
Trabalhar entre Local e Worktree
As árvores de trabalho têm um aspeto e funcionamento muito semelhantes ao seu checkout local. A diferença está no modo como se enquadram no seu fluxo. Pode considerar Local como o primeiro plano e Worktree como o segundo plano. O Handoff permite mover uma conversa entre ambos.
Nos bastidores, o Handoff trata das operações do Git necessárias para mover trabalho entre dois checkouts em segurança. Isto é importante porque o Git só permite que uma branch tenha checkout efetuado num local de cada vez. Se fizer checkout de uma branch numa árvore de trabalho, não pode fazer checkout da mesma branch no seu checkout local em simultâneo, e vice-versa.
Na prática, existem dois percursos comuns:
- Trabalhar exclusivamente na árvore de trabalho. Este percurso é mais adequado quando pode verificar as alterações diretamente na árvore de trabalho, por exemplo, porque instalou dependências e ferramentas através de um script de configuração do ambiente local.
- Transferir a conversa para Local. Utilize este percurso quando quiser trazer a conversa para o primeiro plano, por exemplo, porque pretende inspecionar as alterações no seu IDE habitual ou só pode executar uma instância da aplicação.
Opção 1: trabalhar na árvore de trabalho
Se quiser permanecer exclusivamente na árvore de trabalho com as suas alterações, converta a árvore de trabalho numa branch através do botão Create branch here no cabeçalho da conversa.
A partir daqui, pode fazer commit das alterações, enviar a branch para o repositório remoto e abrir um pull request no GitHub.
Pode abrir o seu IDE na árvore de trabalho através do botão "Open" no cabeçalho, utilizar o terminal integrado ou qualquer outra ferramenta necessária a partir do diretório da árvore de trabalho.
Lembre-se: se criar uma branch numa árvore de trabalho, não pode fazer checkout da mesma em nenhuma outra árvore de trabalho, incluindo o seu checkout local.
Opção 2: transferir uma conversa para Local
Se quiser trazer uma conversa para o primeiro plano, selecione Hand off no cabeçalho da conversa e mova-a para Local.
Este percurso é adequado quando pretende consultar as alterações na janela habitual do seu IDE, executar o servidor de desenvolvimento existente ou validar o trabalho no mesmo ambiente que já utiliza diariamente.
O Codex trata dos passos do Git necessários para mover a conversa em segurança entre a árvore de trabalho e o seu checkout local.
Cada conversa mantém a mesma árvore de trabalho associada ao longo do tempo. Se transferir posteriormente a conversa de volta para uma árvore de trabalho, o Codex devolve-a ao mesmo ambiente em segundo plano, para que possa retomar o trabalho onde ficou.
Também pode seguir o sentido inverso. Se já estiver a trabalhar em Local e quiser libertar o primeiro plano, utilize Hand off para mover a conversa para uma árvore de trabalho. Isto é útil quando pretende que o Codex continue a trabalhar em segundo plano enquanto volta a concentrar-se noutra tarefa local.
Uma vez que o Handoff utiliza operações do Git, quaisquer ficheiros incluídos no seu ficheiro .gitignore não serão movidos com a conversa, a menos que o Codex os copie para uma árvore de trabalho gerida local com .worktreeinclude.
Detalhes avançados
Árvores de trabalho geridas pelo Codex e permanentes
Por predefinição, as conversas utilizam uma árvore de trabalho gerida pelo Codex. Estas árvores foram concebidas para serem leves e descartáveis. Normalmente, uma árvore de trabalho gerida pelo Codex é dedicada a uma conversa, e o Codex devolve essa conversa à mesma árvore de trabalho caso a transfira novamente para lá mais tarde.
Se pretender um ambiente de longa duração, crie uma árvore de trabalho permanente através do menu de três pontos de um projeto na barra lateral. Isto cria uma nova árvore de trabalho permanente como projeto independente. As árvores de trabalho permanentes não são eliminadas automaticamente e pode iniciar várias conversas a partir da mesma árvore de trabalho.
Como o Codex gere as árvores de trabalho por si
O Codex cria árvores de trabalho em $CODEX_HOME/worktrees. O commit inicial é o commit HEAD da branch selecionada quando inicia a tarefa. Se escolher uma branch com alterações locais, o Codex também aplica as alterações não confirmadas à árvore de trabalho. A árvore de trabalho não tem checkout efetuado como branch. Encontra-se num estado detached HEAD. Isto permite ao Codex criar várias árvores de trabalho sem sobrecarregar as suas branches.
Copiar ficheiros locais ignorados para árvores de trabalho geridas
As árvores de trabalho locais geridas pelo Codex começam a partir de um checkout do Git, pelo que os ficheiros controlados já estão presentes. Se o repositório ignorar ficheiros de configuração locais necessários a uma nova árvore de trabalho, adicione um ficheiro .worktreeinclude à raiz do repositório e indique os caminhos ignorados ou os padrões ao estilo de .gitignore que devem ser copiados quando o Codex criar uma árvore de trabalho gerida.
Utilize esta funcionalidade para ficheiros que o Git ignora intencionalmente, como .env, .env.local ou config/secrets.json. O Codex só copia ficheiros ignorados que correspondam a .worktreeinclude; não copia outros ficheiros locais que não sejam controlados pelo Git. Não indique ficheiros controlados.
O Codex copia automaticamente um AGENTS.override.md ignorado para árvores de trabalho geridas locais, pelo que não é necessário indicá-lo em .worktreeinclude.
# .worktreeinclude
.env
.env.local
config/secrets.jsonO Codex ignora links simbólicos de origem e não substitui ficheiros que já existam no novo checkout. Este comportamento aplica-se às árvores de trabalho geridas localmente pela aplicação ChatGPT para computador, não a árvores de trabalho remotas nem a árvores de trabalho do Git que crie através da linha de comandos.
Limitações das branches
Suponha que o Codex conclui algum trabalho numa árvore de trabalho e decide criar uma branch feature/a através de Create branch here. Agora pretende experimentá-la no seu checkout local. Se tentasse fazer checkout da branch, receberia o seguinte erro:
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'Para resolver o problema, teria de fazer checkout de outra branch em vez de feature/a na árvore de trabalho.
Se tenciona fazer checkout da branch localmente, utilize o Handoff para mover a conversa para Local, em vez de tentar manter a mesma branch com checkout efetuado em ambos os locais em simultâneo.
Porque existe esta limitação
O Git impede que a mesma branch tenha checkout efetuado em mais do que uma árvore de trabalho em simultâneo porque uma branch representa uma única referência mutável (refs/heads/<name>), cujo significado é “o estado atual com checkout efetuado” de uma árvore de trabalho.
Quando é feito checkout de uma branch, o Git considera que o respetivo HEAD pertence a essa árvore de trabalho e espera que operações como commits, resets, rebases e merges avancem essa referência de forma bem definida e sequencial. Permitir que várias árvores de trabalho fizessem checkout da mesma branch em simultâneo criaria ambiguidades e condições de corrida quanto às operações de que árvore de trabalho atualizariam a referência da branch, podendo resultar em commits perdidos, índices inconsistentes ou uma resolução de conflitos pouco clara.
Ao impor a regra de uma branch por árvore de trabalho, o Git garante que cada branch tem uma única cópia de trabalho autoritativa, permitindo simultaneamente que outras árvores de trabalho referenciem os mesmos commits em segurança através de detached HEADs ou branches distintas.
Limpeza de árvores de trabalho
As árvores de trabalho podem ocupar muito espaço em disco. Cada uma tem o seu próprio conjunto de ficheiros do repositório, dependências, caches de compilação, entre outros. Por conseguinte, a aplicação ChatGPT para computador tenta manter o número de árvores de trabalho dentro de um limite razoável.
Por predefinição, o Codex mantém as 15 árvores de trabalho geridas pelo Codex mais recentes. Pode alterar este limite ou desativar a eliminação automática nas definições, caso prefira gerir pessoalmente a utilização do disco.
O Codex tenta evitar eliminar árvores de trabalho que ainda sejam importantes. As árvores de trabalho geridas pelo Codex não serão eliminadas automaticamente se:
- Estiverem associadas a uma conversa afixada
- A conversa ainda estiver em curso
- A árvore de trabalho for permanente
As árvores de trabalho geridas pelo Codex são eliminadas automaticamente quando:
- Arquiva a conversa associada
- O Codex precisa de eliminar árvores de trabalho mais antigas para respeitar o limite configurado
Antes de eliminar uma árvore de trabalho gerida pelo Codex, o Codex guarda um instantâneo do trabalho nela contido. Se abrir uma conversa depois de a respetiva árvore de trabalho ter sido eliminada, verá a opção para a restaurar.
Perguntas frequentes
Posso controlar onde são criadas as árvores de trabalho?
Sim. Por predefinição, o Codex cria árvores de trabalho geridas em $CODEX_HOME/worktrees. Para
escolher outra localização, abra Settings > Worktrees e altere
Worktree root.
Posso mover uma conversa entre Local e Worktree?
Sim. Utilize Hand off no cabeçalho da conversa para mover uma conversa entre o seu checkout local e uma worktree. O Codex trata das operações do Git necessárias para mover a conversa em segurança entre ambientes. Se, mais tarde, devolver uma conversa a uma worktree, o Codex devolve-a à mesma worktree associada.
O que acontece às conversas se uma worktree for eliminada?
As conversas podem permanecer no seu histórico mesmo que o diretório da worktree subjacente seja eliminado. No caso de worktrees geridas pelo Codex, o Codex guarda um snapshot antes de eliminar a worktree e permite restaurá-lo se reabrir a conversa associada. As worktrees permanentes não são eliminadas automaticamente quando arquiva as respetivas conversas.