Ramos e revisão

Uma sessão de ramo é uma sessão que trabalha no seu próprio ramo git, na sua própria cópia da pasta de onde veio. Por baixo, isto é uma worktree git: uma segunda cópia de trabalho do mesmo repositório, que partilha o histórico mas tem os seus próprios ficheiros e o seu próprio índice. O seu trabalho na sessão de origem não é tocado. Quando o ramo estiver pronto, integra-o a partir da própria sessão.

Use um ramo para experimentar uma ideia ao lado da linha principal de trabalho, para dividir uma tarefa entre vários agentes que não tropecem nos ficheiros não confirmados uns dos outros, ou para deixar um agente explorar algo que talvez venha a descartar.

Este capítulo cobre também a janela de revisão, que funciona para qualquer sessão com uma pasta, seja ela um ramo ou não.

Iniciar um ramo

Ramifique qualquer sessão que tenha uma pasta:

• clique nela com o botão direito na barra lateral e escolha Novo ramo…
• escolha Novo ramo… no menu ⋯ do cabeçalho da sessão
• escolha Novo ramo… na paleta ⌘K, que age sobre a sessão no palco

A folha Novo ramo diz «Uma sessão só sua, sobre uma cópia de pasta com o seu próprio ramo git. O seu trabalho em «sessão» não é tocado; integre-o quando estiver pronto.» Tem estas partes:

• Começar de (ramo atual): «No commit mais recente — as alterações não confirmadas ficam atrás. Integra de volta nele.»
• Começar de (outro ramo): «No commit mais recente de ramo, e integra de volta em ramo.» O ramo de partida é também o ramo em que a sessão integra de volta.

Sob os campos, a folha mostra o ramo que vai criar, wt/<nome>. O nome passa a minúsculas, com os outros caracteres convertidos em traços. Clique em Iniciar (⌘⏎).

Nota: só o trabalho confirmado é ramificado. As alterações não confirmadas na pasta de origem ficam lá e não são copiadas para a nova cópia.

O que a folha verifica primeiro

A folha pergunta à máquina o que é a pasta («A verificar pasta…») e adapta-se:

• Um repositório: o seletor Começar de descrito acima. Se o repositório tiver um ficheiro .worktreeinclude, a folha acrescenta «Também copia, como o .worktreeinclude indica: …» seguido dos ficheiros que ele lista. São ficheiros que o git não segue, como um .env local, copiados para a nova cópia.
• Um repositório ainda sem commits: «O repositório ainda não tem commits, pelo que o ramo começa num primeiro commit vazio. Os ficheiros da pasta ficam atrás.»
• Não é um repositório: «pasta ainda não é um repositório git, e um ramo precisa de um.» Marque Transformar em um (git init) para correr lá git init. «Tudo o que está na pasta entra num primeiro commit, de onde o ramo parte.» Iniciar fica desativado se esta caixa não estiver marcada.
• A máquina não está em execução: «A máquina não está em execução — a pasta é verificada quando ela arrancar.» A opção Se não for um repositório git, transformar em um aplica-se quando a máquina arrancar.

Dica: os agentes também podem iniciar ramos, com a ferramenta worktree_create do servidor MCP bromure-delegation. Um ramo assim aparece exatamente como um que tivesse iniciado. Ver Agentes a trabalhar em conjunto.

Uma sessão de ramo

Uma sessão de ramo fica aninhada sob a sessão de onde veio, na barra lateral. A sua linha acrescenta um glifo de ramo e uma linha de estado como «3 commits». A linha de estado conta:

• commits à frente do ramo de onde veio («1 commit», «n commits»)
• ficheiros não confirmados («n ficheiros não confirmados»)
• commits em atraso («n atrás»)

Diz «ainda sem alterações» até à primeira alteração. As contagens são lidas da máquina a cada 20 segundos, mais ou menos, enquanto ela corre.

No cabeçalho da sessão, ao lado da pasta, uma etiqueta mostra o nome do ramo e as mesmas contagens. Passe o cursor nela para ler «O seu próprio ramo git, a partir de pai — integre-o quando estiver pronto».

Integrar

Assim que o ramo tiver alterações, o cabeçalho mostra um botão dividido, Integrar em pai.

Clique na parte principal para integrar o ramo naquele de onde veio. A cópia e o ramo são então removidos, e a sessão é arquivada. A sessão continua legível, com uma linha de estado «Integrado em pai».

A parte da seta abre as outras opções, que também estão na secção Ramo dos menus ⋯ e de contexto da sessão:

Uma integração corre assim:

1. Um ramo limpo integra de imediato. Enquanto corre, o cabeçalho diz «A integrar em pai…».
2. Trabalho não confirmado ou um conflito passa para o agente. Quando o ramo tem ficheiros não confirmados, ou a integração entra em conflito, o Bromure desfaz a integração e deixa tudo limpo. Pede então ao agente da própria sessão, na conversa dele, que confirme o trabalho, integre e resolva os conflitos que houver. O cabeçalho diz «A integrar em pai — o agente está a terminá-la», e pode acompanhar no chat. Se o git não tiver identidade na máquina, o commit de integração é feito como Bromure <bromure@localhost>.
3. O Bromure verifica que a integração aterrou antes de remover qualquer coisa. Se não aterrar em 30 minutos, o estado passa a Integração travada: «A integração não aterrou depois de 30 minutos — pergunte ao agente em que ponto está.» O botão diz então Tentar integrar de novo.

Uma integração que estava a decorrer quando saiu é retomada no arranque seguinte.

Quando um agente pede para integrar

Um agente pode pedir para integrar um ramo com a ferramenta worktree_merge. Pode pedir para o seu próprio ramo, ou para um iniciado a partir da sua sessão. Nunca integra por iniciativa própria. Uma faixa aparece sob o cabeçalho da sessão: «O agente pede para integrar ramo em destino». A linha por baixo dá as contagens do ramo, «Como um único commit comprimido» se o agente pediu um squash, e «A cópia é removida assim que a integração aterrar.»

• Revisar alterações abre a janela de revisão.
• Agora não recusa. É dito ao agente para não voltar a pedir a menos que você retome o assunto.
• Integrar (ou Squash e integrar) corre a integração como descrito acima. Quando aterra, o agente que pediu é informado.

Arquivar ou eliminar uma sessão de ramo

Arquivar ou eliminar uma sessão de ramo cujo trabalho não está integrado pergunta o que acontece ao ramo: «Arquivar «sessão» — e o seu ramo?» ou «Eliminar «sessão» — e o seu ramo?».

• Manter ramo deixa a cópia e o ramo na máquina, para poder integrá-lo ou retomá-lo mais tarde. A máquina já não o reabre no arranque. Retomar a sessão volta a abri-lo.
• Descartar ramo elimina a cópia e o ramo com a sessão. «ramo tem trabalho que não está integrado (…)» diz-lhe o que perderia.

Se nada foi feito no ramo («Ainda não foi feito nada em ramo, pelo que não há nada a perder em removê-lo.»), Descartar ramo é a opção por omissão.

Descartar explicitamente, com Descartar ramo…, confirma sempre primeiro: «Descartar «sessão»? O ramo ramo e a sua cópia são eliminados com a sessão. Isto não pode ser desfeito.»

Ramos numa máquina

É fácil perder o rasto dos ramos depois de a sua sessão ser arquivada, integrada ou desaparecer. Ramos nesta máquina… abre uma janela que lista todos os ramos que o Bromure criou numa máquina. Encontra-a no menu ⋯ do cabeçalho da sessão e ao clicar com o botão direito na cápsula da máquina no cabeçalho.

A janela, intitulada «Ramos em máquina», conta «n ramos · n deixados atrás». Cada linha mostra:

• o nome do ramo, e de quem é: Em uma sessão, Sessão pausada, Sessão arquivada, Integrado, ou Sem sessão
• o ramo, uma seta, e o ramo em que integra
• o que contém, e quando foi o último commit
• o caminho da sua cópia na máquina

As ações de cada linha dependem de quem é o ramo:

• Revisar e Mostrar sessão para um ramo que tenha sessão.
• Abrir numa sessão para um ramo que não tenha. Isto inicia o agente predefinido da máquina na cópia do ramo. A nova sessão é uma sessão de ramo completa, pelo que integrar, revisar e descartar funcionam todos.
• O botão do lixo, «Descartar o ramo e a sua cópia», pergunta primeiro. Se o ramo tiver uma sessão arquivada, essa sessão também é eliminada.

Só sem sessão reduz a lista aos ramos deixados atrás. ⌘R atualiza. Os ramos são lidos ao vivo da máquina, pelo que ela tem de estar em execução: «Os ramos são lidos ao vivo da máquina — arranque-a e atualize.»

A janela de revisão

A janela de revisão mostra as alterações de uma sessão como um diff e permite-lhe comentá-las. Não é só para ramos. Há três maneiras de a abrir:

• Revisar alterações, no menu ⋯ da sessão, nos menus Ramo, na paleta ⌘K, ou na faixa de pedido de integração.
• A linha … ficheiros alterados sob uma resposta do agente em o chat. A janela abre então apenas sobre os ficheiros que essa vez alterou («Alterados nesta vez»). Clique em Mostrar tudo para ver tudo, e em Esta vez para voltar a restringir.
• Revisar na janela de ramos.

A janela intitula-se «Revisão — sessão». As suas partes:

• O seletor de comparação («Com o que as alterações são comparadas»):
  • Desde pai existe só para sessões de ramo, e é a predefinição delas. Mostra tudo o que o ramo tem e o seu pai não.
  • Não confirmado mostra as alterações ainda não confirmadas. É a predefinição para as outras sessões.
  • Último commit mostra o commit mais recente.
• A lista de ficheiros mostra quantos ficheiros mudaram, «n de n vistos» com uma barra de progresso, e os commits do ramo. Os ficheiros novos que o git ainda não segue estão incluídos e contados («n ficheiros novos ainda não adicionados ao git»). Clique num ficheiro para saltar para ele.
• Marcar como visto. O círculo ao lado de cada ficheiro marca-o como olhado, e ele recolhe-se. A marca está ligada ao diff atual do ficheiro, pelo que volta se o ficheiro mudar outra vez.
• O diff. Passe o cursor numa linha para a comentar. Também pode comentar um ficheiro («Um comentário sobre este ficheiro») ou, no campo em baixo, a alteração toda.
• O cabeçalho tem um botão Atualizar (⌘R) e Abrir terminal, mais o botão de integração numa sessão de ramo.

Comentários

Um comentário que acrescenta (⏎) é um rascunho: «espera com os outros até os enviar». ⌥⏎ acrescenta uma nova linha. O × remove um rascunho.

Enviar n comentários ao agente (⇧⌘⏎) envia todos os rascunhos ao agente da sessão numa única mensagem numerada, cada comentário com o seu ficheiro e linha, e pede ao agente que os trate. Se o agente não estiver a correr, a mensagem retoma-o. Os comentários enviados ficam na janela marcados «enviado». Os comentários e as marcas de visto são guardados com a sessão e sobrevivem ao fecho da janela.

As alterações são lidas ao vivo da máquina. Se ela estiver desligada, a janela diz «Não é possível alcançar a máquina»: arranque a máquina e atualize.

Nota: as tarefas de código usam a mesma janela de revisão, com botões próprios das tarefas, como Devolver com n comentários.

Terminais das máquinas

Os separadores do terminal Linux de uma máquina mantêm as ações de worktree mais antigas: Novo worktree (⇧⌘G), Integrar worktree (⇧⌘M) e Anexar um terminal, no menu Espaços de trabalho. Ver Máquinas. Para as sessões de agente, as ações de ramo acima substituem-nas.

Num servidor espelhado e no iOS

As sessões de ramo, a integração, a faixa de pedido de integração, a janela de revisão e a janela de ramos funcionam todas numa janela de cliente pesado a espelhar outro Mac. Os clientes iPhone e iPad oferecem Novo worktree… no menu de toque longo de uma sessão, que abre a mesma folha de ramo. Onde o seu menu de ramo aparece, Descartar ramo… abre um submenu, Descartar — isto não pode ser desfeito, em vez do diálogo de confirmação.