Setup and Config
Getting and Creating Projects
Basic Snapshotting
Branching and Merging
Sharing and Updating Projects
Inspection and Comparison
Patching
Debugging
External Systems
Server Admin
- 2.43.2 → 2.45.2 no changes
- 2.43.1
02/09/24 - 2.42.2 → 2.43.0 no changes
- 2.42.1
11/02/23
- 2.42.0
08/21/23
- 2.39.1 → 2.41.2 no changes
- 2.39.0
12/12/22
- 2.36.1 → 2.38.5 no changes
- 2.36.0
04/18/22
- 2.35.1 → 2.35.8 no changes
- 2.35.0
01/24/22
- 2.33.1 → 2.34.8 no changes
- 2.33.0
08/16/21
- 2.31.1 → 2.32.7 no changes
- 2.31.0
03/15/21
- 2.30.1 → 2.30.9 no changes
- 2.30.0
12/27/20
- 2.29.1 → 2.29.3 no changes
- 2.29.0
10/19/20
- 2.28.1 no changes
- 2.28.0
07/27/20
- 2.22.1 → 2.27.1 no changes
- 2.22.0
06/07/19
- 2.20.1 → 2.21.4 no changes
- 2.20.0
12/09/18
- 2.19.3 → 2.19.6 no changes
- 2.19.2
11/21/18
- 2.19.1 no changes
- 2.19.0
09/10/18
- 2.18.1 → 2.18.5 no changes
- 2.18.0
06/21/18
- 2.17.1 → 2.17.6 no changes
- 2.17.0
04/02/18
- 2.16.6
12/06/19
- 2.14.6 → 2.15.4 no changes
- 2.13.7
05/22/18
- 2.12.5
09/22/17
- 2.11.4 no changes
- 2.10.5
09/22/17
- 2.9.5
07/30/17
- 2.8.6 no changes
- 2.7.6
07/30/17
- 2.6.7
05/05/17
- 2.5.6
05/05/17
RESUMO
git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]] [--orphan] [(-b | -B) <novo-ramo>] <caminho> [<commit-ish>] git worktree list [-v | --porcelain [-z]] git worktree lock [--reason <string>] <árvore-de-trabalho> git worktree move <worktree> <novo-caminho> git worktree prune [-n] [-v] [--expire <expira>] git worktree remove [-f] <árvore-de-trabalho> git worktree repair [<caminho>…] git worktree unlock <árvore-de-trabalho>
DESCRIÇÃO
Gerencie várias árvores de trabalho conectadas ao mesmo repositório.
A git repository can support multiple working trees, allowing you to check out more than one branch at a time. With git worktree add a new working tree is associated with the repository, along with additional metadata that differentiates that working tree from others in the same repository. The working tree, along with this metadata, is called a "worktree".
This new worktree is called a "linked worktree" as opposed to the "main worktree" prepared by git-init[1] or git-clone[1]. A repository has one main worktree (if it’s not a bare repository) and zero or more linked worktrees. When you are done with a linked worktree, remove it with 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.
COMANDOS
- add <caminho> [<commit-ish>]
Crie uma árvore de trabalho no
<caminho>e faça a averiguação<commit-ish>nele. A nova árvore de trabalho está vinculada ao repositório atual, compartilhando tudo exceto arquivos específicos da árvore de trabalho, como o HEAD, o índice, etc. Por conveniência o<commit-ish>pode ser um simples "-", que é um sinônimo de@{-1}.If
<commit-ish>is a branch name (call it<branch>) and is not found, and neither-bnor-Bnor--detachare used, but there does exist a tracking branch in exactly one remote (call it<remote>) with a matching name, treat as equivalent to:$ git worktree add --track -b <ramo> <caminho> <remoto>/<ramo>
Caso o ramo exista em diversos ramos remotos e um deles seja nomeado pela variável de configuração
checkout.defaultRemote, para propósitos de desambiguação, mesmo que<ramo>não seja o único em todos os outros ramos remotos. Defina por exemplo,checkout.defaultRemote=originpara que sempre verifique as ramificações remotas de lá caso<ramo>seja ambíguo e ainda assimoriginexista. Consulte tambémcheckout.defaultRemoteem git-config[1].If
<commit-ish>is omitted and neither-bnor-Bnor--detachused, then, as a convenience, the new worktree is associated with a branch (call it<branch>) named after$(basename <path>). If<branch>doesn’t exist, a new branch based onHEADis automatically created as if-b <branch>was given. If<branch>does exist, it will be checked out in the new worktree, if it’s not checked out anywhere else, otherwise the command will refuse to create the worktree (unless--forceis used).If
<commit-ish>is omitted, neither--detach, or--orphanis used, and there are no valid local branches (or remote branches if--guess-remoteis specified) then, as a convenience, the new worktree is associated with a new unborn branch named<branch>(after$(basename <path>)if neither-bor-Bis used) as if--orphanwas passed to the command. In the event the repository has a remote and--guess-remoteis used, but no remote or local branches exist, then the command fails with a warning reminding the user to fetch from their remote first (or override by using-f/--force).- list
List details of each worktree. The main worktree is listed first, followed by each of the linked worktrees. The output details include whether the worktree is bare, the revision currently checked out, the branch currently checked out (or "detached HEAD" if none), "locked" if the worktree is locked, "prunable" if the worktree can be pruned by the
prunecommand.- lock
If a worktree is on a portable device or network share which is not always mounted, lock it to prevent its administrative files from being pruned automatically. This also prevents it from being moved or deleted. Optionally, specify a reason for the lock with
--reason.- move
Mova uma árvore de trabalho para um novo local. Observe que a principal árvore de trabalho ou as árvores de trabalho vinculadas que contenham submódulos, não poderão ser movidas com este comando. (Contudo o comando
git worktree repairpode restabelecer a conexão com as árvores de trabalho vinculadas a ela caso você mova manualmente a principal árvore de trabalho.)- prune
Remova a informação da árvore de trabalho no
$GIT_DIR/worktrees.- remove
Remova uma árvore de trabalho. Somente a árvore de trabalho que estiver vazia (sem arquivos não monitorados e nenhuma alteração nos arquivos monitorados) pode ser removida. A árvore de trabalho que não estiver vazia ou com os sub-módulos podem ser removidas a força com a opção
--force. A principal árvore de trabalho não pode ser removida.- repair [<caminho>…]
Faz o reparo dos arquivos administrativos da árvore de trabalho caso tenham se corrompido ou tenham se desatualizado devido a fatores externos.
Por exemplo, caso a principal árvore de trabalho (ou o repositório vazio) seja movida, as outras árvores de trabalho que estejam vinculadas à ela não serão capazes de localizá-la. Ao executar o comando
repairna principal árvore de trabalho, fará com que a conexão das árvores de trabalho que estejam vinculadas sejam restauradas de volta para a principal árvore de trabalho.Da mesma forma, caso uma árvore de trabalho vinculada seja movida sem usar o comando
git worktree move, a principal árvore de trabalho (ou o repositório vazio) não será capaz de localizá-la. Executando o comandorepairdentro da árvore de trabalho recém-movida faz com que a conexão seja reestabelecida. Caso várias árvores de trabalho que estejam vinculadas sejam movidas, ao executar orepaira partir de qualquer árvore de trabalho usando o novo<caminho>de cada árvore como argumento, o vínculo será reestabelecido com todos os caminhos especificados.Caso a principal árvore de trabalho e as árvores de trabalho que estejam vinculadas tenham sido movidas manualmente, ao executar
repairna principal árvore de trabalho e ao definir um novo<caminho>de cada árvore de trabalho vinculada, fará com que todas as conexões em todas as direções sejam reestabelecidas.- unlock
Desbloqueie uma árvore de trabalho em funcionamento, permitindo que ela seja removida, movida ou excluída.
OPÇÕES
- -f
- --force
É predefinido que
addse recuse a criar uma nova árvore de trabalho quando<commit-ish>for um nome de um ramo e já esteja em averiguação por outra árvore de trabalho, ou caso o<caminho>já esteja atribuído a alguma árvore de trabalho, porém esteja ausente (caso o<caminho>tenha sido excluído manualmente por exemplo). Esta opção substitui estas salvaguardas. Para adicionar um caminho numa árvore de trabalho ausente e que esteja bloqueada, utilize a opção--forceduas vezes.o
movese recusa a mover uma árvore de trabalho bloqueada a menos que a opção--forceseja utilizada duas vezes. Caso o destino já esteja atribuído a alguma outra árvore de trabalho, porém esteja ausente (caso o<novo-caminho>tenha sido excluído manualmente por exemplo), então a opção--forcepermite que a ação de mover prossiga; utilize a opção--forceduas vezes caso o destino esteja bloqueado.removerefuses to remove an unclean worktree unless--forceis used. To remove a locked worktree, specify--forcetwice.- -b <novo-ramo>
- -B <novo-ramo>
With
add, create a new branch named<new-branch>starting at<commit-ish>, and check out<new-branch>into the new worktree. If<commit-ish>is omitted, it defaults toHEAD. By default,-brefuses to create a new branch if it already exists.-Boverrides this safeguard, resetting<new-branch>to<commit-ish>.- -d
- --detach
Com
add, desanexe oHEADna nova árvore de trabalho. Consulte "HEAD DESANEXADO" em git-checkout[1].- --[no-]checkout
É predefinido que
addfaça a averiguação do<commit-ish> `, no entanto a opção `--no-checkoutpode ser utilizado para suprimir a averiguação a fim de fazer as personalizações, como configurar a averiguação esparsa. Consulte "Averiguação esparsa" em git-read-tree[1].- --[no-]guess-remote
Com
worktree add <caminho>, sem<commit-ish>, em vez de criar uma nova ramificação a partir doHEAD, caso exista uma ramificação de rastreamento em exatamente um ponto remoto que coincida com obasenamedo<caminho>, baseie a nova ramificação na ramificação remota rastreada e marque a ramificação rastreada remoto como um "upstream" da nova ramificação.Isso também pode ser definido como um comportamento predefinido ao usar a opção da configuração
worktree.guessRemote.- --[no-]track
When creating a new branch, if
<commit-ish>is a branch, mark it as "upstream" from the new branch. This is the default if<commit-ish>is a remote-tracking branch. See--trackin git-branch[1] for details.- --lock
Mantenha a árvore de trabalho bloqueada após a criação. Isso é equivalente ao comando
git worktree lockapósgit worktree add, porém sem a condição de corrida.- -n
- --dry-run
Com
prune, não remove nada; apenas relate o que seria removido.- --orphan
With
add, make the new worktree and index empty, associating the worktree with a new unborn branch named<new-branch>.- --porcelain
With
list, output in an easy-to-parse format for scripts. This format will remain stable across Git versions and regardless of user configuration. It is recommended to combine this with-z. See below for details.- -z
Termine cada linha com um NUL em vez de uma nova linha quando a opção
--porcelainfor usada comlist. Isto torna possível analisar a saída quando o caminho da árvore de trabalho tiver um novo caractere de uma nova linha.- -q
- --quiet
Com
add, suprima as mensagens de feedback.- -v
- --verbose
Com
prune, relate todas as remoções.Com
list, produza informações adicionais sobre as árvores de trabalho (veja abaixo).- --expire <tempo>
Com
prune, expire apenas a árvore de trabalho que não foram utilizadas e que sejam mais velhas que<tempo>.Com
list, anote a árvore de trabalho que estejam ausentes como podáveis e caso sejam mais antigas do que<tempo>.- --reason <texto>
Com
lockou comadd --lock, uma explicação é dada do por que a árvore está "locked" (travada).- <árvore de trabalho>
A árvore de trabalho pode ser identificada através do seu caminho, seja ele relativo ou absoluto.
Caso os componentes do último caminho da árvore de trabalho sejam únicos entre as árvores, ele poderá ser utilizado para identificar a árvore de trabalho. Como por exemplo, caso tenha apenas duas árvores de trabalho, em
/abc/def/ghie/abc/def/ggg,ghioudef/ghiserão suficientes para apontar para a antiga árvore de trabalho.
REFS
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.
Geralmente, cada árvore de trabalho possuí uma ref própria e todas as refs que iniciem com refs/ podem ser compartilhados. Os pseudo-refs são aqueles como HEAD que estão diretamente sob $GIT_DIR ao invés de estarem dentro do GIT_DIR/refs. Contudo há exceções: as refs não serão compartilhadas quando estiverem dentro do refs/bisect, refs/worktree e refs/rewritten.
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.
ARQUIVO DE CONFIGURAÇÃO
By default, the repository config file is shared across all worktrees. If the config variables core.bare or core.worktree are present in the common config file and extensions.worktreeConfig is disabled, then they will be applied to the main worktree only.
Você pode ativar a extensão worktreeConfig para ter uma configuração específica para as árvores de trabalho, por exemplo:
$ git config extensions.worktreeConfig true
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:
core.worktreenunca deve ser compartilhado.core.barenão deve ser compartilhado caso o valor sejacore.bare=true.Recomenda-se a opção de configuração
core.sparseCheckoutnão seja compartilhada, a menos que você tenha certeza de utilizar a verificação esparsa em todas as árvores de trabalho.
Para mais detalhes consulte a documentação sobre extensions.worktreeConfig em git-config[1].
DETALHES
Each linked worktree has a private sub-directory in the repository’s $GIT_DIR/worktrees directory. The private sub-directory’s name is usually the base name of the linked worktree’s path, possibly appended with a number to make it unique. For example, when $GIT_DIR=/path/main/.git the command git worktree add /path/other/test-next next creates the linked worktree in /path/other/test-next and also creates a $GIT_DIR/worktrees/test-next directory (or $GIT_DIR/worktrees/test-next1 if test-next is already taken).
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.
To prevent a $GIT_DIR/worktrees entry from being pruned (which can be useful in some situations, such as when the entry’s worktree is stored on a portable device), use the git worktree lock command, which adds a file named locked to the entry’s directory. The file contains the reason in plain text. For example, if a linked worktree’s .git file points to /path/main/.git/worktrees/test-next then a file named /path/main/.git/worktrees/test-next/locked will prevent the test-next entry from being pruned. See gitrepository-layout[5] for details.
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.
FORMATO DA LISTA DE SAÍDA
The worktree list command has two output formats. The default format shows the details on a single line with columns. For example:
$ git worktree list /path/to/bare-source (bare) /path/to/linked-worktree abcd1234 [master] /path/to/other-linked-worktree 1234abc (HEAD desanexado)
The command also shows annotations for each worktree, according to its state. These annotations are:
locked, caso a árvore de trabalho esteja bloqueada.prunable, caso a árvore de trabalho possa ser podada através do comandogit worktree prune.
$ git worktree list /path/to/linked-worktree abcd1234 [master] /path/to/locked-worktree acbd5678 (brancha) bloqueado /path/to/prunable-worktree 5678abc (HEAD desanexada) podável
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.
$ git worktree list --verbose /path/to/linked-worktree abcd1234 [master] /path/to/locked-worktree-no-reason abcd5678 (HEAD desanexado) bloqueado /path/to/locked-worktree-with-reason 1234abcd (brancha) bloqueado: a árvore de trabalho está montando em um dispositivo portátil /path/to/prunable-worktree 5678abc1 (HEAD desanexado) podável: o arquivo gitdir aponta para um local que não existe
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.
Formato Porcelana
The porcelain format has a line per attribute. If -z is given then the lines are terminated with NUL rather than a newline. Attributes are listed with a label and value separated by a single space. Boolean attributes (like bare and detached) are listed as a label only, and are present only if the value is true. Some attributes (like locked) can be listed as a label only or with a value depending upon whether a reason is available. The first attribute of a worktree is always worktree, an empty line indicates the end of the record. For example:
$ git worktree list --porcelain worktree /path/to/bare-source bare worktree /path/to/linked-worktree HEAD abcd1234abcd1234abcd1234abcd1234abcd1234 branch refs/heads/master worktree /path/to/other-linked-worktree HEAD 1234abc1234abc1234abc1234abc1234abc1234a detached worktree /path/to/linked-worktree-locked-no-reason HEAD 5678abc5678abc5678abc5678abc5678abc5678c branch refs/heads/locked-no-reason locked worktree /path/to/linked-worktree-locked-with-reason HEAD 3456def3456def3456def3456def3456def3456b branch refs/heads/locked-with-reason locked reason why is locked worktree /path/to/linked-worktree-prunable HEAD 1233def1234def1234def1234def1234def1234b detached prunable gitdir file points to non-existent location
Unless -z is used any "unusual" characters in the lock reason such as newlines are escaped and the entire reason is quoted as explained for the configuration variable core.quotePath (see git-config[1]). For Example:
$ git worktree list --porcelain ... locked "reason\nwhy is locked" ...
EXEMPLOS
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.
$ git worktree add -b emergency-fix ../temp master $ pushd ../temp # ... hack hack hack ... $ git commit -a -m 'correção de emergência para o chefe' $ popd $ git worktree remove ../temp
BUGS
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.
GIT
Parte do conjunto git[1]
