Git
Português (Brasil) ▾ Topics ▾ Latest version ▾ git-bundle last updated in 2.41.0

NOME

git-bundle - Mova os objetos e as refs através do arquivo

RESUMO

git bundle create [-q | --quiet | --progress]
		    [--version=<versão>] <arquivo> <git-rev-list-args>
git bundle verify [-q | --quiet] <arquivo>
git bundle list-heads <file> [<refname>…​]
git bundle unbundle [--progress] <file> [<refname>…​]

DESCRIÇÃO

Crie, desempacote e manipule os arquivos "bundle" (pacote). Os pacotes são usados para a transferência "offline" dos objetos Git sem um "servidor" ativo esperando do outro lado da conexão de rede.

Eles podem ser usados para criar backups incrementais e completos de um repositório e para retransmitir o estado das referências de um repositório para outro.

Os comandos do Git que buscam ou "leem" através de protocolos como ssh:// e https:// também podem operar nos arquivos de pacote (bundle). É possível git-clone[1] (clonar) um novo repositório a partir de um pacote, usar o comando git-fetch[1] para buscar a partir de um e para listar as referências contidas nele usando o comando git-ls-remote[1]. Não há suporte correspondente de "gravação", ou seja, não há suporte para fazer um git push num pacote.

Consulte a seção de EXEMPLOS abaixo para mais exemplos de como usar.

FORMATO BUNDLE

Os pacotes são arquivos .pack (consulte git-pack-objects[1]) com um cabeçalho indicando quais as referências estão contidas nele.

Como o próprio formato de arquivo comprimido, os pacotes podem ser autônomos ou criados usando exclusões. Consulte a seção "PRÉ-REQUISITOS DO OBJETO" abaixo.

Os pacotes criados usando exclusões de revisão são "pacotes finos" criados usando a opção --thin para git-pack-objects[1] (empacotar os objetos), e descompactados usando a opção --fix-thin para git-index-pack[1].

Não há opção de criar um "pacote grosso" ao usar as exclusões de revisão, e os usuários não devem estar preocupados com essa diferença. Ao usar "pacotes finos", os pacotes "bundles" criados usando exclusões são menores em tamanho. A questão de serem "finos" sob o capô é meramente notado aqui como uma curiosidade e como uma referência a outra documentação.

Consulte gitformat-bundle[5] para obter mais detalhes e informações sobre o "thin pack" em gitformat-pack[5].

OPÇÕES

create [options] <arquivo> <git-rev-list-args>

Usado para criar um pacote chamado file. Isso requer os argumentos <git-rev-list-args> para definir o conteúdo do pacote. Já options contém as opções específicas do subcomando git bundle create. Se o file for - o pacote será enviado para "stdout".

verify <arquivo>

Usado para verificar se um arquivo do pacote é válido e se será aplicado de forma limpa ao repositório atual. Isso inclui verificações no próprio formato do pacote, bem como a verificação se exitem pré-requisitos do commits e se estão totalmente vinculados no repositório atual. Em seguida, o git bundle imprime uma lista de commits ausentes, se for o caso. Por fim, são impressas informações sobre recursos adicionais, como o "filtro de objetos". Para mais informações consulte "Capacidades" do comando gitformat-bundle[5]. Caso seja bem-sucedido o código de encerramento é zero, mas se torna um caso o arquivo do pacote seja inválido. Se o file for - o pacote será lido de "stdin".

list-heads <arquivo>

Lista as referências definidas no pacote. Se for seguido por uma lista de referências, serão impressas apenas as referências que correspondam à lista informada. Se o file for - o pacote será lido de "stdin".

unbundle <arquivo>

Encaminha os objetos do pacote para git index-pack para armazenamento no repositório e, em seguida, imprime os nomes de todas as referências definidas. Se for fornecida uma lista de referências, apenas serão impressas as referências correspondentes às da lista. Esse comando é totalmente redirecionável, tem a única função de ser invocado pelo comando git fetch. Se o file for - o pacote será lido de "stdin".

<git-rev-list-args>

Uma lista de argumentos, é aceitável com o comando git rev-parse e com o git rev-list (e contendo uma referência mencionada, consulte ESPECIFICANDO REFERÊNCIAS abaixo), que especifica os objetos e as referências específicos que serão transportados. Por exemplo, master~10..master faz com que a referência mestre atual seja empacotada junto com todos os objetos adicionados desde o décimo commit do seu ancestral. Não há limite explícito para a quantidade de referências e de objetos que podem ser empacotados.

[<refname>…​]

Uma lista de referências utilizadas para limitar as referências relatadas como disponíveis. É muito útil para ser utilizado com o git fetch que espera receber apenas as referências solicitadas e não necessariamente tudo no pacote (nesse caso, git bundle age como git fetch-pack).

--progress

É predefinido que a condição geral do progresso seja relatada no fluxo de erros quando estiver conectado num terminal, a menos que -q seja utilizado. Esta opção impõem a condição geral do progresso, mesmo que o fluxo de erro predefinido não seja direcionado para um terminal.

--version=<versão>

Especifique uma versão para o pacote. A versão 2 é o formato mais antigo e só pode ser usado com repositórios SHA-1; a versão 3 mais recente, contém recursos que permitem extensões. A predefinição é o formato compatível mais antigo, com base no algoritmo de hash em uso.

-q
--quiet

Esta opção faz com que o comando não relate o seu progresso em meio ao fluxo de erros já predefinido.

ESPECIFICANDO AS REFERÊNCIAS

As revisões devem ser acompanhadas pelos nomes de referência que serão empacotados num pacote (bundle).

Mais de uma referência pode ser empacotada e mais de um conjunto de objetos de pré-requisito podem ser especificados. Os objetos empacotados são aqueles que não estão presentes na união dos pré-requisitos.

O comando git bundle create resolve para você, os nomes de referência, usando as mesmas regras do comando git rev-parse --abbrev-ref=loose. Cada pré-requisito pode ser definido de forma explicita (como ^master~10 por exemplo) ou implicitamente (master~10..master, --since=10.days.ago master por exemplo).

Todos estes casos simples funcionam (assumindo que temos um ramo "master" e "next"):

$ git bundle create master.bundle master
$ echo master | git bundle create master.bundle --stdin
$ git bundle create master-and-next.bundle master next
$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin

E assim são estes (e os mesmos, mas omitidos, exemplos --stdin):

$ git bundle create recent-master.bundle master~10..master
$ git bundle create recent-updates.bundle master~10..master next~5..next

Um nome para a revisão ou intervalo não é aceito quando o lado direito não pode ser resolvido uma referência:

$ git bundle create HEAD.bundle $(git rev-parse HEAD)
fatal: Recusando a criação de um pacote vazio.
$ git bundle create master-yesterday.bundle master~10..master~5
fatal: Recusando a criação de um pacote vazio.

PRÉ-REQUISITOS DO OBJETO

Ao criar os pacotes, é possível criar um pacote independente que pode ser descompactado num repositório sem um histórico em comum, além de fornecer revisões negativas para excluir objetos necessários nas partes anteriores do histórico.

A alimentação de uma revisão como new (nova) para git bundle create criará um arquivo pacote que contém todos os objetos acessíveis a partir da nova revisão. Esse pacote pode ser descompactado em qualquer repositório obtendo assim uma história completa que leva até à nova revisão:

$ git bundle create full.bundle new

Um intervalo de revisão como old..new produzirá um arquivo de pacote que exigirá que a revisão old (e quaisquer outros objetos acessíveis a partir dele) exista para que o pacote possa ser "desagregado":

$ git bundle create full.bundle old..new

Um pacote independente e sem qualquer pré-requisito, pode ser extraído em qualquer lugar, mesmo num repositório vazio ou pode ser clonado a partir de (ou por exemplo, new mas não old..new).

É bom errar pelo excesso de zelo, fazendo com que o arquivo bundle (pacote) contenha os objetos já no destino, pois eles são ignorados durante a descompactação no destino.

Se quiser corresponder a git clone --mirror, que incluiria as suas referências, como refs/remotes/*, use o comando --all. Caso queira fornecer o mesmo conjunto de referências que um clone obteria diretamente do repositório da origem, use a opção --branches --tags no <git-rev-list-args>.

O comando git bundle verify pode ser usado para verificar se o repositório do destinatário tem os pré-requisitos necessários para fazer o commit de um pacote.

EXEMPLOS

Suponha que você queira transferir o histórico de um repositório R1 na máquina A para outro repositório R2 na máquina B. Por qualquer motivo, a conexão direta entre A e B não é permitida, mas podemos mover os dados de A para B através de algum mecanismo (CD, e-mail etc.). Queremos atualizar o R2 com o desenvolvimento feito no ramo master de R1.

Para inicializar o processo, você pode primeiro criar um pacote que não exista qualquer pré-requisitos. Você pode usar uma tag para ser lembrado até o último commit que for processado, serve para facilitar a atualização posterior do outro repositório com um pacote incremental:

machineA$ cd R1
machineA$ git bundle create file.bundle master
machineA$ git tag -f lastR2bundle master

Em seguida, você transfere file.bundle para a máquina no destino B. Como esse pacote não requer que nenhum objeto existente seja extraído, você pode criar um novo repositório na máquina B clonando a partir dele:

machineB$ git clone -b master /home/me/tmp/file.bundle R2

Isso irá definir um ponto remoto chamado "origin" (origem) no repositório que permite que você capture e extraia do pacote. O arquivo $GIT_DIR/config no R2 terá uma entrada como esta:

[remote "origin"]
    url = /home/me/tmp/file.bundle
    fetch = refs/heads/*:refs/remotes/origin/*

Para atualizar o repositório mine.git, você pode capturar ou extrair após a reposição do pacote armazenado em /home/me/tmp/file.bundle com as atualizações incrementais.

Depois de trabalhar um pouco mais no repositório original, você pode criar um pacote incremental para atualizar um outro repositório:

machineA$ cd R1
machineA$ git bundle create file.bundle lastR2bundle..master
machineA$ git tag -f lastR2bundle master

Em seguida, você transfere o pacote para uma outra máquina para substituir o /home/me/tmp/file.bundle e captura dele.

machineB$ cd R2
machineB$ git pull

Caso saiba até qual commit do repositório nos destinatários pretendidos devem ter os objetos necessários, você poderá utilizar este conhecimento para definir o pré-requisito, informando um ponto de corte para limitar as revisões e os objetos inclusos no pacote. O exemplo anterior utilizou a tag lastR2bundle para essa finalidade, porém é possível utilizar outras opções que você daria ao comando git-log[1]. Aqui mais alguns exemplos:

Você pode utilizar uma tag que esteja presente em ambos:

$ git bundle create mybundle v1.0.0..master

Você pode utilizar um pré-requisito utilizando o tempo como referência:

$ git bundle create mybundle --since=10.days master

Você pode utilizar a quantidade dos commits:

$ git bundle create mybundle -10 master

Você pode executar o comando git-bundle verify para ver se você consegue extrair de um pacote que foi criado com um pré-requisito:

$ git bundle verify mybundle

Isso listará quais os commits você deve ter para extrair do pacote e encerrará com um erro caso você não os tenha.

Um pacote do ponto de vista de um repositório do destinatário é como um repositório regular do qual ele captura ou extrai. Você pode, por exemplo, durante a captura é possível mapear quais são as referências:

$ git fetch mybundle master:localRef

Você também pode ver quais são as referências que ela oferece:

$ git ls-remote mybundle

FORMATO DO ARQUIVO

Consulte gitformat-bundle[5].

GIT

Parte do conjunto git[1]

scroll-to-top