git-worktree - Gerencie as várias árvores de trabalho

Gerencie várias árvores de trabalho conectadas ao mesmo repositório.

Um repositório git pode suportar várias árvores de trabalho, permitindo que você verifique mais de um ramo de cada vez. Com o comando git worktree add, uma nova árvore de trabalho é associada ao repositório, juntamente com os metadados adicionais que diferenciam esta árvore de trabalho das outras no mesmo repositório. A árvore de trabalho, juntamente com estes metadados, é chamada de "worktree".

Esta nova árvore de trabalho é chamada de "linked worktree" (árvore de trabalho vinculada), em oposição à "main worktree" (árvore de trabalho principal) preparada pelo comando git-init[1] ou o comando git-clone[1]. Um repositório tem uma árvore de trabalho principal (se não for um repositório simples) e zero ou mais árvore de trabalho vinculadas. Quando você terminar de usar uma árvore de trabalho vinculada, remova-a com o comando git worktree remove.

Em sua forma mais simples, o comando git worktree add <caminho> cria automaticamente um novo ramo cujo nome é o componente final do <caminho>, que é conveniente caso planeje trabalhar em um novo tópico. Por exemplo, o comando git worktree add ../hotfix cria um novo ramo hotfix e elimina o caminho ../ hotfix. Para trabalhar num ramo existente em uma nova árvore de trabalho, use o comando git worktree add <caminho> <ramo>. Por outro lado, caso queira apenas planejar fazer algumas alterações experimentais ou realizar testes sem atrapalhar o desenvolvimento já existente, em geral é conveniente criar uma árvore de trabalho descartável e que não seja associada com nenhum ramo. Por exemplo, o comando git worktree add -d <caminho> cria uma nova árvore de trabalho com um HEAD separado no mesmo commit do ramo atual.

Caso uma árvore de trabalho seja excluída sem o a utilização do comando git worktree remove, os seus arquivos administrativos associados, que residam no repositório (consulte "DETALHES" abaixo), serão removidos automaticamente (consulte a opção de configuração gc.worktreePruneExpire no git-config[1]), ou é possível executar o comando git worktree prune na árvore principal ou em qualquer árvore de trabalho vinculada para fazer a limpeza de quaisquer arquivos administrativos que estejam obsoletos.

Caso uma árvore de trabalho vinculada estiver armazenada num dispositivo portátil ou num compartilhamento da rede que nem sempre seja montado, é possível impedir que os seus arquivos administrativos sejam removidos emitindo o comando git worktree lock, utilizando opcionalmente a opção --reason para explicar por que a árvore de trabalho está bloqueada.

Quando utilizar diversas árvores de trabalho, algumas refs são compartilhadas entre todas as árvores de trabalho mas outras são específicas para cada árvore de trabalho individualmente. Um exemplo é o HEAD, que é único para cada a árvores de trabalho. Esta seção são sobre as regras de compartilhamento e de como acessar tais refs de uma árvore de trabalho para outra.

In general, all pseudo refs are per-worktree and all refs starting with refs/ are shared. Pseudo refs are ones like HEAD which are directly under $GIT_DIR instead of inside $GIT_DIR/refs. There are exceptions, however: refs inside refs/bisect, refs/worktree and refs/rewritten are not shared.

As refs individuais de cada árvore de trabalho ainda podem ser acessadas de uma outra árvore de trabalho através de dois caminhos especiais, main-worktree e worktrees. A primeira oferece acesso ref individual a cada principal árvore de trabalho, enquanto a última a todas as árvores de trabalho que forem vinculadas à ela.

Como por exemplo, main-worktree/HEAD ou main-worktree/refs/bisect/good resolve para o mesmo valor que HEAD nas principais árvores de trabalho, assim como refs/bisect/good respectivamente. Da mesma forma, worktrees/foo/HEAD e worktrees/bar/refs/bisect/bad são as mesmas que $GIT_COMMON_DIR/worktrees/foo/HEAD e $GIT_COMMON_DIR/worktrees/bar/refs/bisect/bad.

Para acessar as refs é melhor não olhar diretamente para dentro do $GIT_DIR. Em vez disso, use comandos como o git-rev-parse[1] ou git-update-ref[1] que manipularão corretamente as refs.

É predefinido que o arquivo config do repositório seja compartilhado em todas as árvores de trabalho. Se as variáveis de configuração core.bare ou core.worktree estiverem presentes no arquivo de configuração comum e extensions.worktreeConfig estiver desativado, elas serão aplicadas somente à árvore de trabalho principal.

Você pode ativar a extensão worktreeConfig para ter uma configuração específica para as árvores de trabalho, por exemplo:

Neste modo, a configuração específica permanece no caminho apontado pelo comando git rev-parse --git-path config.worktree. Você pode adicionar ou atualizar a configuração neste arquivo com o comando git config --worktree. As versões mais antigas do Git se recusarão a acessar os repositórios com esta extensão.

Observe que neste arquivo, a exceção para core.bare e core.worktree desapareceu. Caso existam no $GIT_DIR/config, você deve movê-los para o config.worktree da árvore principal de trabalho. Você também pode aproveitar esta oportunidade para revisar e mover as outras configurações que não deseja compartilhar com todas as árvores de trabalho:

Para mais detalhes consulte a documentação sobre extensions.worktreeConfig em git-config[1].

Cada árvore de trabalho vinculada tem um subdiretório privado no diretório $GIT_DIR/worktrees do repositório. O nome do subdiretório privado geralmente é o nome base do caminho da árvore de trabalho vinculada, possivelmente acrescido de um número para torná-lo exclusivo. Por exemplo, quando $GIT_DIR=/path/main/.git, o comando git worktree add /path/other/test-next next cria a árvore de trabalho vinculada em /path/other/test-next e também cria um diretório $GIT_DIR/worktrees/test-next (ou $GIT_DIR/worktrees/test-next1 se o test-next já estiver ocupado).

Dentro de uma árvore de trabalho vinculada, $GIT_DIR é configurado para apontar para este diretório privado (/path/main/.git/worktrees/test-next no exemplo) e $GIT_COMMON_DIR é configurado para apontar de volta para a principal árvore de trabalho $GIT_DIR (/path/main/.git por exemplo). Estas configurações são feitas em um arquivo .git localizado no diretório mais alto do vínculo da árvore de trabalho.

A resolução do caminho através do comando git rev-parse --git-path utiliza $GIT_DIR ou $GIT_COMMON_DIR, dependendo do caminho. Na árvore de trabalho vinculada, o comando git rev-parse --git-path HEAD retorna /path/main/.git/worktrees/test-next/HEAD (não /path/other/test-next/.git/HEAD ou /path/main/.git/HEAD) enquanto o comando git rev-parse --git-path refs/heads/master usa $GIT_COMMON_DIR e retorna /path/main/.git/refs/heads/master, já que as refs são compartilhados em todas as árvores de trabalho, exceto refs/bisect, refs/worktree e refs/rewritten.

Para mais informações consulte gitrepository-layout[5]. A regra geral é não fazer qualquer suposição sobre se um caminho pertence ao $GIT_DIR ou ao $GIT_COMMON_DIR quando você precisar acessar diretamente algo dentro do $GIT_DIR. Para obter o caminho final utilize o comando git rev-parse --git-path.

Caso queira mover o vínculo de uma árvore de trabalho manualmente, será preciso atualizar o arquivo gitdir no diretório da entrada. Como por exemplo, caso o vínculo de uma árvore de trabalho seja movida para /newpath/test-next e o seu arquivo .git aponte para /path/main/.git/worktrees/test-next, então atualize /path/main/.git/worktrees/test-next/gitdir para a referência /newpath/test-next. Melhor ainda, execute o comando git worktree repair para restabelecer a conexão automaticamente.

Para evitar que uma entrada $GIT_DIR/worktrees seja removida (o que pode ser útil em algumas situações, como quando a árvore de trabalho da entrada é armazenada num dispositivo portátil), use o comando git worktree lock, que adiciona um arquivo chamado locked ao diretório da entrada. O arquivo contém o motivo em texto simples. Por exemplo, se o arquivo .git de uma árvore de trabalho vinculada apontar para /path/main/.git/worktrees/test-next então o arquivo chamado /path/main/.git/worktrees/test-next/locked impedirá que a entrada test-next seja eliminada. Para mais detalhes consulte gitrepository-layout[5].

Quando a opção de configuração extensions.worktreeConfig está ativo, o arquivo de configuração .git/worktrees/<id>/config.worktree é lido após o .git/config.

O comando worktree list tem dois formatos de saída. O formato predefinido mostra os detalhes numa única linha com colunas. Por exemplo:

O comando também mostra as anotações para cada árvore de trabalho, de acordo com a sua condição. Estas anotações são:

Para essas anotações, um motivo também pode estar disponível e isso pode ser visto usando o modo detalhado. A anotação é então movida para a próxima linha recuada seguida pelas informações adicionais.

Observe que a anotação é movida para a próxima linha caso a informação adicional esteja disponível, caso contrário, ela permanece na mesma linha que a própria árvore de trabalho.

Você está no meio de uma sessão de refatoração e o seu chefe entra e exige que você conserte algo imediatamente. Você normalmente pode usar o git-stash[1] para armazenar temporariamente as suas alterações, no entanto, a sua árvore de trabalho está em uma condição de desordem (com arquivos novos, movidos e removidos e outros pedaços espalhados) que você não quer arriscar mexer em nenhum deles. Em vez disso, você cria uma árvore de trabalho vinculada temporária para fazer a correção de emergência, removê-la quando terminar e em seguida, retomar a sua sessão de refatoração anterior.

A averiguação múltipla em geral ainda é experimental e a compatibilidade para os submódulos ainda está incompleto. NÃO é recomendado fazer várias averiguações de um superprojeto.

Parte do conjunto git[1]