Scroll to navigation

git-debrebase(5) git-debrebase git-debrebase(5)

NOME

git-debrebase - modelo de dados git para empacotamento Debian

INTRODUÇÃO

git-debrebase é uma ferramenta para representar e manipular em git pacotes Debian baseados no código fonte do autor.

O empacotamento Debian tem um histórico de avanço rápido. A fila delta (alterações aos ficheiros do autor) é representada como uma série de cometidos git individuais, os quais podem ser trabalhados com re-base, e também serem partilhados.

DISCUSSÃO

O git-debrebase é desenhado para funcionar bem com o dgit. O git-debrebase também pode ser usado em fluxos de trabalho sem pacotes fonte, por exemplo para trabalhar em pacotes de formato Debian fora ou paralelamente a Debian.

O próprio git-debrebase não é muito apropriado para usar por derivados de Debian, para trabalhar em pacotes herdados de Debian, porque assume que você quer deitar fora qualquer empacotamento fornecido pelo seu autor. No entanto, o uso de git-debrebase em Debian não torna nada mais difícil para derivados, e pode facilitar algumas coisas.

Quando se usa gitk e ramos geridos pelo git-debrebase, gitk --date-order, gitk --first-parent e gitk -- :. (ou gitk .) produzem resultados mais úteis que a predefinição.

TERMINOLOGIA

Uma fusão que na realidade não funde as árvores; em vez disso, é construída ao tomar a árvore de um dos pais (ignorando os conteúdos dos outros pais). Estas são usadas para fazer um rescrever de histórico de avanço rápido a partir da ponta anterior, para que possa ser empurrada e puxada normalmente. A construção manual de pseudo-fusões pode ser feita com "git merge -s ours" mas não é normalmente necessário quando se usa git-debrebase.
Ficheiros na árvore fonte dentro de debian/, excluindo qualquer coisa em debian/patches/.
A versão do pacote sem o empacotamento Debian. Tipicamente fornecido pelo real autor do projeto, e por vezes seguido por contribuidores de Debian num ramo "upstream".

A autoria contém ficheiros do autor, mas algumas autorias também contêm ficheiro de empacotamento em debian/. Quaisquer tais ficheiros não-autor encontrados na autoria são deitadas fora pelo git-debrebase cada vez que uma nova versão de autor é incorporada.

Ficheiros na árvore fonte Files fora de debian/. Estes podem incluir fonte não modificada do autor, mas também ficheiros que foram modificados ou criados para Debian.
Alterações Debian aos ficheiros do autor: uma série de cometidos git.
Ficheiros em debian/patches/ gerados para o benefício do formato de pacote fonte .dsc (quilt) 3.0 do dpkg-source. Não usados, geralmente apagados, e regenerados quando necessário (tal como ao enviar para Debian), pelo git-debrebase.
Veja "RAMOS E ESTADOS DE RAMO - VISÃO GERAL".
Âncora; Empacotamento
Veja "CONTEÚDOS DE RAMOS - ESPECIFICAÇÃO DETALHADA".
Veja "COSER, PSEUDO-FUSÕES, REGISTO FFQ".

DIAGRAMA

           ------/--A!----/--B3!--%--/--> vista de intercâmbio
                /        /          /      com directório debian/
               %        %          %       fila delta inteira aplicada
              /        /          /        3.0 (quilt) tem debian/patches
             /        /          3*       "master" em servidores git Debian
            /        /          /
           2*       2*         2
          /        /          /
         1        1          1    ramo quebra-mar, fundindo linha base
        /        /          /     código de autor não modificado
    ---@-----@--A----@--B--C      mais debian/ (mas nenhum debian/patches)
      /     /       /                     nenhuma referência refer a isto: nós
   --#-----#-------#-----> autoria        re-constrói a sua identidade ao
                                           inspecionar ramo de intercâmbio
    Chave:
      1,2,3   cometidos que tocam apenas em ficheiros de autor
      A,B,C   cometidos que tocam apenas em debian/
      B3      cometido misturado (ex feito por um NMUer)
      #       lançamentos do autor
     -@-      fusão âncora, toma conteúdo de debian/ a partir do
     /         anterior cometido `breakwater' e o resto da autoria
     -/-      pseudo-fusão; conteúdos são idênticos a
     /         pai inferior no diagrama.
      %       cometido gerado dgit- ou git-debrebase- de debian/patches.
              apenas `3.0 (quilt)'; geralmente descartado pelo git-debrebase.
      *       CABEÇALHO de Maintainer estava aqui enquanto estavam a editar,
              antes de dizerem que estava pronto, que nesse ponto as suas
              ferramentas fizeram -/- (e talvez %) para converter para
              o ramo de intercâmbio de avanço rápido.
      !       CABEÇALHO do NMUer estava aqui quando disseram `dgit push'.
              Rebase lavagem de ramo converte cada ! em um
              * equivalente.

RAMOS E ESTADOS DE RAMO - VISÃO GERAL

O git-debrebase tem um ramo principal, o ramo de intercâmbio. Este ramo encontra-se em estações de trabalho de contribuidores Debian (tipicamente, um maintainer iria chama-lo de master), no servidor git dgit de Debian como o ramo da suite (dgit/dgit/sid) e em outros servidores git que suportem trabalho Debian (ex master em salsa).

O ramo de intercâmbio é de avanço rápido (por virtude de pseudo-fusões, onde necessárias).

É possível ter múltiplos ramos de intercâmbio diferentes para o mesmo pacote, armazenados como diferentes ramos git locais e remotos. No entanto, a divergência deve ser evitada onde possível - veja "OUTRAS FUSÕES".

Um ramo de intercâmbio apropriado pode ser usado diretamente com o dgit. neste caso, cada ramo de site de arquivo do dgit é um ramo de intercâmbio separado.

Dentro do que é ancestral no ramo de intercâmbio, existe outro ramo importante e implícito, o breakwater. Este quebra mar contém a fonte do autor não modificada, mas com o empacotamento de Debian super-imposto (substituindo qualquer directório "debian/" que possam estar nos cometidos do autor). O quebra mar não contém nenhuma representação da fila delta (nem mesmo debian/patches). A parte do quebra mar processada pelo git-debrebase é a parte desde a âncora mais recente, o que geralmente é uma fusão especial gerada pelo git-debrebase.

Quando se trabalha, localmente, o ramo do utilizador pode estar num estado de re-basear, conhecido como unstitched. Enquanto um ramo está não cosido, não está no formato de intercâmbio. A ponta de ramo de intercâmbio anterior é gravada, para que o histórico anterior e o trabalho do utilizador possam mais tarde ser cosidos no formato de intercâmbio de avançar rápido.

Um ramo não cosido pode estar em estado lavado, o que significa que tem um formato especial particular mais conveniente para manipulação da fila delta.

CONTEÚDOS DE RAMOS - ESPECIFICAÇÃO DETALHADA

É mais conveniente descreve o ramo breakwater primeiro. Um quebra mar é de avançar-rápido, mas não geralmente nomeado por uma referência. Ele contém por esta ordem (ancestrais primeiro):

Âncora
Um cometido âncora, o qual é geralmente ma fusão de dois-pais especial:

O primeiro pai contém a versão mais recente, nesse ponto, do empacotamento Debian (em debian/); muitas vezes também contém ficheiros do autor, mas eles são para serem ignorados. Geralmente o primeiro pai é uma ponta de quebra mar anterior.

O segundo pai é um cometido de fonte de autor. Pode por vezes conter um sub-directório debian/, mas se sim é para ser ignorado. Os ficheiros de autor do segundo pai são idênticos aos da âncora. As fusões de âncora contêm sempre "[git-debrebase anchor: ...]" com o uma linha na mensagem de cometido.

Em alternativa, uma âncora pode ser um cometido de único-pai o qual introduz o directório "debian/" e não faz mais nenhuma alteração: isto é, o iniciar do empacotamento Debian.

Zero ou mais cometidos de único-pai contendo apenas alterações de empacotamento. (E nenhumas alterações de patch quilt.)

O estado do ramo lavado é re-basear. Um ramo lavado é baseado num quebra mar mas também contém, adicionalmente, após o quebra mar, uma representação da fila delta:

Zero ou mais cometidos de único-pai contendo apenas alterações aos ficheiros do autor.

O estado de ramo meramente não-cosido (isto é, não-cosido mas não-lavado) é também re-basear. Tem o mesmo conteúdo que o estado lavado, excepto que pode conter, adicionalmente, em qualquer ordem mas depois do quebra mar:

Cometido(s) posteriores que contêm alterações aos ficheiros do autor e/ou para o empacotamento, possivelmente misturadas dentro dum cometido único. (Mas não alterações de patch quilt.)
Cometido(s) que adicionam patches a debian/patches/, e adicionam essas patches ao final de series.

Estes são apenas necessários quando se trabalha com pacotes em formato ".dsc 3.0 (quilt)". Para o git-debrebase eles são puramente uma saída; eles são apagados quando os ramos são lavados. O git-debrebase toma conta de fazer uma série de patch a partir da fila delta, para que quaisquer pacotes fonte resultantes fiquem bem.

Finalmente, um ramo intercâmbio é avanço-rápido. Tem o mesmo conteúdo que um ramo em estado não lavado, mas pode (e geralmente irá) adicionalmente conter (em alguma ordem, provavelmente inter-misturada com os cometidos extra que podem ser encontrados num ramo não cosido e não lavado):

Uma pseudo-fusão que torna o ramo de avanço rápido a partir do histórico anterior. O pai contribuidor está ele próprio em formato de intercâmbio. Normalmente o pai sobrescrito é uma ponta anterior de um ramo de intercâmbio, mas isto não é necessário pois o pai sobrescrito não é examinado.

Se os dois pais tiverem árvores idênticas, aquele com a data de cometido mais tarde (ou, se as datas de cometido forem iguais, o primeiro pai) é tratado como o pai contribuinte.

Importações de pacote fonte Debian .dsc feitas pelo dgit (durante busca dgit de um pacote enviado muito recentemente para Debian sem dgit, ou durante dgit import-dsc).

O git-debrebase requer que cada tal importação esteja no formato de avanço rápido produzido pelo dgit: uma pseudo-fusão de dois pais, cujo pai contribuinte está no formato de importação dsc do dgit de não-avanço-rápido (não descrito mais aqui), e cujo pai sobrescrito é a ponta de intercâmbio anterior (ex. a ponta prévia do ramo de suite dgit).

COSER, PSEUDO-FUSÕES, REGISTO FFQ

Sempre que o ramo "refs/B" é descosido, o cabeçalho anterior é gravado na referência git "refs/ffq-prev/B".

Os ramos descosidos não são de avanço rápido a partir dos ramos de intercâmbio publicados [1]. Assim antes de um ramo poder ser empurrado, a pseudo-fusão certa tem de ser restabelecida. Isto é a operação de coser, a qual consome a referência ffq-prev.

Quando o utilizador tem um ramo descosido, ele pode rescreve-lo livremente, a partir da ponta de quebra mar em diante. Tal re-basear git é a operação predefinida para o git-debrebase. Os re-basear não devem recuar antes da ponta do quebra mar, e certamente não antes da âncora mais recente.

Ramos descosidos não podem ser empurrados para referências de ramo de intercâmbio (pelo uso de "git push -f" ou equivalente). Pode-se partilhar um ramo descosido em circunstâncias semelhantes com avisos semelhantes para partilhar qualquer outro ramo git de re-basear.

[1] Estritamente, para um pacote que nunca teve uma fila delta Debian, os ramos de intercâmbio e quebra mar podem ser idênticos, que nesse caso o ramo descosido é de avanço rápido a partir do ramo de intercâmbio e nenhuma pseudo-fusão é necessária.

Quando ffq-prev não está presente, "refs/debrebase-last/B" regista algum ancestral de refs/B, (geralmente, o resultado da última costura). Isto é usado para escrita de estado e algumas verificações de erros - especialmente para escrever pistas sobre o que será o problema. Para determinar se o ramo está a ser mantido no formato git-debrebase é necessário consultar o seu histórico.

OUTRAS FUSÕES

Note que a representação descrita aqui não permite fusões gerais de nenhum dos ramos relevantes. Por esta razão as ferramentas irão tentar ajudar o utilizador a evitar divergência do ramo de intercâmbio.

Veja dgit-maint-debrebase(7) para uma discussão sobre que tipos de comportamentos devem ser evitados porque podem gerar tais fusões.

O histórico (fusões) não linear no ramo de intercâmbio é estranho porque não preserva (obviamente) a linearidade da fila delta. A fusão fácil de filas delta divergentes é um problema de estudo.

Se for detetada uma fusão geral, o git-debrebase irá tratar cada lado da fusão como um ramo de intercâmbio do git-debrebase, e irá tentar resolver ambos numa vista coerente. Quando esta tentativa tem sucesso, assume-se que o resultado esteja correto.

Se a resolução automática falhar, uma pilha incompreensível de destroços de fusão multidimensional será deixada em referências git sob "refs/debrebase/wreckage/". É provável que você não consiga resolver isto sem ajuda especializada. Se isto acontecer, por favor reporte um bug, com os Passos para Reprodução formais, incluindo o URL do seu repositório público, o cometido git preciso do seu ramo atual.

OPERAÇÕES LEGAIS

As seguintes operações básicas seguidas a partir deste modelo (consulte o diagrama em cima):

Independentemente do estado do ramo, é sempre bom simplesmente cometer git (ou escolher etc.) cometidos que contêm alterações a ficheiros do autor, alterações de empacotamento, ou ambos.

(Isto pode tornar o ramo não lavado.)

Grava o cabeçalho anterior em ffq-prev, se foi costurado anteriormente (e apaga debrebase-last).

Reorganiza o ramo atual para que as alterações de empacotamento venham primeiro, seguido da fila delta, afinando "-@-A-1-2-B3" em "...@-A-B-1-2-3".

Descarta pseudo-fusões e quaisquer adições de patch quilt.

Com um ramo lavado, pode-se fazer um re-basear git interactivo da fila delta.
Arranca re-basear em uma nova versão de autor, tornando "...#..@-A-B-1-2-3" em "(...#..@-A-B-, ...#'-)@'-1-2".

Isto tem de ser um invólucro em volta do git-rebase, que prepara @' e depois tenta re-basear 1 2 em @'. Se o utilizador pedir um re-basear interactivo, @' não aparece na lista de cometidos, pois @' é a nova base do re-basear (veja git-rebase(1)).

Note que a construção de @' não pode falhar porque @' simplesmente copia debian/ de B e todo o resto de #'. (Re-basear A e B é indesejável. Nós queremos que os ficheiros debian/ sejam não-re-baseados para que o relatório git mostre o histórico de empacotamento.)

Faz uma pseudo fusão, cujo pai contribuinte é o ramo descosido e cujo pai sobreposto é ffq-prev, consumindo ffq-prev no processo (e escrevendo debrebase-last em vez disso). Idealmente o pai contribuinte seria um ramo lavado, ou talvez um ramo lavado com cometido de adição de patch quilt.
Para gerar uma árvore que pode ser representada como um pacote fonte .dsc 3.0 (quilt), a fila delta tem de ser reificada dentro da árvore git em debian/patches/. Estes ficheiros patch podem ser despidos e/ou regenerados como necessário.

OPERAÇÕES ILEGAIS

Algumas operações git não são permitidas neste modelo de dados. Efetua-las irá quebrar o git-debrebase.

Veja "OUTRAS FUSÕES", em cima.
O git-rebase não deve ser invocado de tal maneira que a base escolhida fica antes da âncora, ou antes da última pseudo-fusão. Isto porque o git-rebase destrói fusões. git rebase --preserve-merges também é perigoso.

O git-rebase sem um argumento base irá muitas vezes arrancar demasiado cedo.

Por estas razões, é melhor usar o git-debrebase e deixa-lo escolher a base para o seu re-basear. Se você perceber que cometeu este erro, é melhor usar o reflog para recuperar para um estado anterior bom e apropriado.

debian/patches é uma saída do git-debrebase, e não uma entrada. Se você editar patches o git-debrebase irá reclamar e recusar a trabalhar. Se você adicionar patches o mais provável é que o seu trabalho seja descartado.

Em vez de editar as patches, use git-debrebase para editar os cometidos correspondentes.

O CABEÇALHO prévio, que irá ser pseudo-fundido por operações como git-debrebase stitch, é gravado num nome de referência derivado a partir do seu nome de ramo.

Se você renomear ramos descosidos, esta informação pode sair do passo.

Por outro lado, criar um novo ramo a partir dum ramo descosido é bom para fazer um ramo para brincar com ele, mas o resultado não pode ser cosido.

ANOTAÇÕES DE MENSAGEM DE COMETIDO

O git-debrebase faz anotações nas mensagens de cometido que gera.

O formato geral é

  [git-debrebase TIPO-DE-COMETIDO [ ARGUMENTOS...]: PROSA, MAIS PROSA]

O git-debrebase trata qualquer coisa após os dois pontos como um comentário, não prestando nenhuma atenção à PROSA.

O conjunto completo de anotações é:
[git-debrebase split: cometido misturado, parte debian]
[git-debrebase split: cometido misturado, parte do autor]
[git-debrebase convert dgit import: alterações debian]
[git-debrebase anchor: converter importação dgit, alterações do autor]

  [git-debrebase upstream-combine . PIECE[ PIECE...]: nova autoria]
  [git-debrebase anchor: nova autoria NOVA-VERSÃO-AUTOR, fusão]
  [git-debrebase changelog: nova autoria NOVA-VERSÃO-AUTOR]
  [git-debrebase make-patches: exportar e cometer patches]
  [git-debrebase convert-from-gbp: descarta patches]
  [git-debrebase anchor: declara autoria]
  [git-debrebase pseudomerge: cose]
  [git-debrebase merged-breakwater: construído a partir de fusão vanilla]
  [git-debrebase convert-to-gbp: cometer patches]
  [git-debrebase convert-from-dgit-view upstream-import-convert: VERSÃO]
  [git-debrebase convert-from-dgit-view drop-patches]

Apenas fusões âncora têm a etiqueta "[git-debrebase anchor: ...]". As âncoras de pai único não são geradas pelo git-debrebase, e quando feitas manualmente não devem conter nenhuma anotação "[git-debrebase ...]".

As etiquetas "split mixed commit" e "convert dgit import" são adicionadas A`mensagem de cometido pré-existente, quando o git-debrebase rescreve o cometido.

APÊNDICE - MANUSEAMENTO DE IMPORTAÇÃO DO DGIT

O formato de importação .dsc do dgit não está documentando nem especificado (assim alguns dos termos seguintes não estão definidos em lado nenhum). O formato de importação do dgit é definido pela implementação no dgit, do qual git-debrebase tem conhecimento especial.

Considere um NMU não-dgit seguido de um NMU dgit:

            intercâmbio --/--B3!--%--//----D*-->
                         /          /
                        %          4
                       /          3
                      /          2
                     /          1
                    2          &_
                   /          /| \
                  1          0 00 =XBC%
                 /
                /
          --@--A     quebra mar
           /
        --#--------> autoria
 Chave suplementar:
    =XBC%     importação tarball dgit de .debian.tar.gz contendo
               empacotamento Debian incluindo alterações B C e patches quilt
    0         importação tarball dgit do tarball do autor
    00        importação tarball dgit de parte de autor suplementar
    &_        importação dgit de âncora-quase-quebra-mar
    //        busca dgit / pseudo-fusão import-dsc para tornar avanço rápido
    &'        importação convertida ao git-debrebase (apenas ficheiros de autor)
    C'        importação de alterações de empacotamento convertidas ao git-debrebase
    * **      antes e depois de CABEÇALHO

Nós queremos transformar isto em:

 (0 + 00 eq #)
                        --/--B3!--%--//-----D*-------------/-->
                         /          /                     /
                        %          4                     4**
                       /          3                     3
                      /          2                     2
                     /          1                     1
                    2          &_                    /
                   /          /| \                  /
                  1          0 00 =XBC%            /
                 /                                /
                /                                /
          --@--A-----B---------------------C'---D
           /
        --#----------------------------------------->
    
 (0 + 00 neq #)
                        --/--B3!--%--//-----D*-------------/-->
                         /          /                     /
                        %          4                     4**
                       /          3                     3
                      /          2                     2
                     /          1                     1
                    2          &_                    /
                   /          /| \                  /
                  1          0 00 =XBC%            /
                 /                                /
                /                                /
          --@--A-----B-----------------@---C'---D
           /                          /
        --#--------------------- - - / - - --------->
                                    /
                                   &'
                                  /|
                                 0 00

VEJA TAMBÉM

git-debrebase(1), dgit-maint-rebase(7), dgit(1)

dgit+tag2upload team Debian Project