dgit-maint-debrebase(7)

NOME
dgit - tutorial para maintainers de pacote, usando um fluxo de trabalho centrado em redor do git-debrebase(1)

INTRODUÇÃO
Este documento descreve elementos dum fluxo de trabalho para manter um pacote Debian não-nativo usando git-debrebase e git-debpush, e um pouco de dgit. Nós mantemos o delta Debian como uma série de cometidos git no nosso ramo mestre. Nós usados git-debrebase(1) para misturar o nosso ramo de tal modo que esta série de cometidos git aparece no fim do ramo. Todo o histórico git público é avançado-rápido, isto é, não rescrevemos nem forçamos o empurrar.

Algumas vantagens deste fluxo de trabalho:

•   Manipular a fila delta usado o poder total do git-rebase(1), em vez de confiar em quilt(1), e sem ter que mudar para a frente e para trás entre ramos de patches-aplicadas e patches-não-aplicadas ao cometer alterações e ao tentar compilar, como com o gbp-pq(1).

•   Se você está a usar 3.0 (quilt), forneça a sua fila delta como uma série de patches quilt separadas por propriedades no pacote fonte que você enviou para o arquivo (ao contrário de com dgit-maint-merge(7)).

•   Evite que a árvore git fique suja pelo aplicar ou desaplicar de patches, pois elas são sempre aplicadas.

•   Beneficia das capturas de segurança do dgit e tag2upload. Em particular, assegura que o seu envio corresponde sempre exatamente ao seu CABEÇALHO git.

•   Forneça um histórico git completo num formato standard em dgit-repos, onde pode beneficiar os utilizadores do dgit de fluxos abaixo, tais como pessoas que usam o dgit para fazer um NMU (veja dgit-nmu-simple(7) e dgit-user(7)).

•   Minimiza a quantidade de conhecimento que você precisa de ter sobre 3.0 (quilt) de modo a manter pacotes fonte Debian que usam esse formato.

Este fluxo de trabalho é apropriado para pacotes onde o delta Debian contém múltiplas peças que interagem, ou os quais você não espera estar capaz de enviar ao autor em breve. Para pacotes com deltas Debian simples e/ou de vida curta, o uso de git-debrebase(1) introduz complexidade desnecessária. Para tais pacotes, considere o fluxo de trabalho descrito em dgit-maint-merge(7).

A DEBIANIZAÇÃO INICIAL
Esta secção explica como começar a usar este fluxo de trabalho com um novo pacote. Deve ser saltada quando se converte um pacote existente para este fluxo de trabalho.

  Quando etiquetas de autor são lançadas em git
Supondo que o lançamento de autor estável mais recente é 1.2.2, e isto foi etiquetado '1.2.2' pelo autor.

    % git clone -oupstream https://some.upstream/foo.git
    % cd foo
    % git verify-tag 1.2.2
    % git reset --hard 1.2.2
    % git remote add -f origin git@salsa.debian.org:debian/foo.git
    % git push --follow-tags -u origin master

O comando final também tem o efeito de desanexar o seu ramo mestre do remoto do autor, assim esse git não tenta enviar nada para lá, ou fundir cometidos do autor não lançados.

Agora siga e Debianise o seu pacote. Faça cometidos no ramo mestre, adicionando coisas no directório debian/, ou aplicando patches na fonte do autor. Por razões técnicas, é essencial que o seu primeiro cometer introduza o directório debian/ contendo pelo menos um ficheiro, e não faça mais nada. Por outras palavras, faça um cometido a introduzir debian/ antes de aplicar patches à fonte do autor.

Finalmente, você precisa dum tarball original:

    % git deborig

Veja git-deborig(1) se isto falhar.

Este tarball é efémero e facilmente regenerado, assim não o cometemos para lado nenhum (ex. com ferramentas como o pristine-tar(1)).

Comparar lançamentos de tarball do autor

    O que está em cima assume que você sabe como compilar o pacote a partir de git e que isso é feito diretamente.

    Se, como um utilizador da fonte do autor, você geralmente compilar a partir de lançamentos em tarball do autor, em vez de etiquetas git do autor, você vai descobrir que por vezes a árvore git não contém tudo o que está no tarball.

    Podem ser necessários passos de compilação adicionais. Por exemplo, você poderá precisar do seu debian/rules para correr ferramentas automáticas.

    Você pode comparar o lançamento em tarball do autor, e a etiqueta git do autor, dentro do git, a importar o tarball para o git como descrito na próxima secção, usando um valor diferente para 'upstream-tag', e depois usando git-diff(1) para comparar o tarball importado com a etiqueta de lançamento.

Usando cometidos de autor não etiquetados

    Por vezes o autor não etiqueta os seus lançamentos, ou você quer empacotar um instantâneo de git não lançado. Em tais casos você pode criar a sua própria etiqueta de lançamento de autor, no formato upstream/ver, onde ver é a versão de autor que você planeia colocar em debian/changelog. O prefixo upstream/ assegura que a sua etiqueta não vai colidir com nenhumas etiquetas que o autor crie mais tarde.

    Por exemplo, suponha que o lançamento mais recente do autor é 1.2.2 e você quer empacotar o cometido git ab34c21 que foi feito em 2013-12-11. Uma convenção comum é usar a versão de autor número 1.2.2+git20131211.ab34c21 e assim você podia usar

        % git tag -s upstream/1.2.2+git20131211.ab34c21 ab34c21

    para obter a etiqueta de lançamento, e depois proceder como em cima.

    Pode-se gerar tal etiqueta versionada usando a opção --pretty do git show, ex.:

        % git tag -s upstream/$(git show --date=format:%Y%m%d --pretty=format:"1.2.2+git%cd.%h" --quiet upstream/main) upstream/main

  Quando o autor lança apenas tarballs
Porque nós queremos trabalhar em git, precisamos dum ramo de autor virtual com etiquetas de lançamento virtuais. O gbp-import-orig(1) pode gerir isto para nós. Para começar

    % mkdir foo
    % cd foo
    % git init
    % git checkout -b upstream
    % gbp import-orig \
        --upstream-branch=upstream --debian-branch=master \
        --upstream-tag='upstream/%(version)s' \
        --sign-tags --no-pristine-tar \
        ../foo_1.2.2.orig.tar.xz
    % git branch -f upstream

Isto deve deixa-lo no ramo mestre. De seguida, o nosso ramo de autor não pode ser empurrado para dgit-repos, mas como precisamos dele sempre que importamos uma nova versão de autor, temos de o meter nalgum lado. A escolha do costume é salsa.debian.org:

    % git remote add -f origin salsa.debian.org:debian/foo.git
    % git push --follow-tags -u origin master upstream

Você agora está pronto para prosseguir como em cima, fazendo cometidos para o directório debian/ e para a fonte do autor. Como em cima, por razões técnicas, é essencial que o primeiro cometer introduza o directório debian/ contendo pelo menos um ficheiro, e não faça mais nada. Por outras palavras, faça um cometido a introduzir debian/ antes de aplicar patches à fonte do autor.

Uma maneira conveniente de assegurar que este requerimento está satisfeito é começar por criar debian/gbp.conf:

    [DEFAULT]
    upstream-branch = upstream
    debian-branch = master
    upstream-tag = upstream/%(version)s

    sign-tags = True
    pristine-tar = False
    pristine-tar-commit = False

    [import-orig]
    merge = False

e cometer isso:

    % git add debian/gbp.conf && git commit -m "create gbp.conf"

Note que não conseguimos criar debian/gbp.conf antes de agora pelas mesmas razões técnicas que requerem que o nosso primeiro cometer introduza debian/ sem aplicar patches à fonte do autor. É por isto que tivemos de passar muitas opções à nossa primeira chamada ao gbp-import-orig(1).

CONVERTER UM PACOTE EXISTENTE
Esta secção explica como converter um pacote Debian existente para este fluxo de trabalho. Deve ser saltada quando se está a debianizar um pacote novo.

Se você tem um histórico git existente que enviou para um servidor git normal como o salsa.debian.org, nós começamos com isso. Se você já não o tiver localmente, vai precisar de o clonar, e obter o orig.tar correspondente a partir do arquivo:

    % git clone salsa.debian.org:debian/foo
    % cd foo
    % dgit setup-new-tree
    % origtargz

Se você não tem um histórico git existente, ou tem o histórico apenas no servidor especial dgit-repos, começamos com dgit clone:

    % dgit clone foo
    % cd foo

Então nós temos novas etiquetas de autor disponíveis:

    % git remote add -f upstream https://some.upstream/foo.git

Agora nós usamos um comando git debrebase convert-from-* para converter o seu histórico existente para o modelo de dados git-debrebase(5). Qual comando você deve usar depende de alguns factos sobre o seu repositório:

(A) Não existe uma fila delta.
    Se não existirem nenhumas patches Debian, use

        % git debrebase convert-from-gbp

(B) Existe uma fila delta, e as patches não estão aplicadas.
    Este é o fluxo de trabalho standard do git-buildpackage(1): existem patches Debian, mas a fonte do autor é cometida ao git sem essas patches aplicadas. Use

        % git debrebase convert-from-gbp

    Se você não estava a usar dgit para enviar o seu pacote (isto é, você não estava a usar o fluxo de trabalho descrito em dgit-maint-gbp(7)), e você correu dgit fetch sid neste clone do repositório, vai precisar de passar --fdiverged a este comando.

(C) Existe uma fila delta, e as patches estão aplicadas.
    Use

        % git debrebase convert-from-dgit-view

Finalmente, você precisa assegurar que o seu CABEÇALHO git e compatível com dgit, isto é, é exatamente o que obteria se apagasse .git, invocasse dpkg-buildpackage -S, e depois desempacotasse o pacote fonte resultante.

Para conseguir isto, você pode precisar de apagar debian/source/local-options. Uma maneira de ter o dgit a verificar o seu progresso é correr dgit build-source.

CONFIGURAÇÃO DO GIT
O git-debrebase(1) ainda não suporta usar git merge para fundir ramos divergentes de desenvolvimento (veja "OUTRAS FUSÕES" em git-debrebase(5)). Você deve configurar o git de maneira que git pull não tente a fusão:

    % git config --local pull.rebase true

Agora quando você puxar trabalho de outros contribuidores de Debian, o git irá re-basear o seu trabalho por cima do deles.

Se você usar este clone para desenvolvimento de autor em adição em trabalho de empacotamento Debian, pode não querer definir esta definição global. Em vez disto, veja as definições branch.autoSetupRebase e branch.<name>.rebase em git-config(5).

IMPORTAR NOVOS LANÇAMENTOS DO AUTOR
Existem dois passos: obter referências git que correspondem ao novo lançamento, e importar esse lançamento usando git-debrebase(1).

  Obtendo o lançamento
Quando etiquetas de autor são lançadas em git

    % git fetch --tags upstream

Se você quer empacotar um cometido de autor não etiquetado (porque o autor não etiqueta os lançamentos ou porque você quer empacotar um instantâneo de desenvolvimento do autor), veja "Usando cometidos de autor não etiquetados" em cima.

Quando o autor lança apenas tarballs

Você vai precisar do debian/gbp.conf de "Quando o autor lança apenas tarballs", em cima. Você vai também precisar do seu ramo de autor. Em cima, nós envia-mos isto para salsa.debian.org. Você vai precisar de clonar ou ir buscar de lá, em vez de confiar apenas em dgit clone/dgit fetch.

Então, ou

    % gbp import-orig ../foo_1.2.3.orig.tar.xz

ou se você tiver um ficheiro watch a funcionar

    % gbp import-orig --uscan

  Importar o lançamento
    % git debrebase new-upstream 1.2.3

Esta invocação de git-debrebase(1) envolve um git re-base. Você pode precisar de resolver conflitos se a fila delta Debian não se aplicar de modo limpo à nova fonte do autor.

Se tudo correu bem, você pode agora rever a fusão do novo lançamento do autor:

    git diff debian/1.2.2-1..HEAD -- . ':!debian'

Também, faça diff com --name-status e --diff-filter=ADR para ver apenas a lista de ficheiros adicionados ou removidos, o que é útil para determinar se existem ficheiros novos ou apagados que possam ter de ser declarados no seu ficheiro copyright.

Se você obteve um tarball a partir do autor, está pronto para tentar uma compilação. Se você fundiu uma etiqueta git a partir do autor, você vai precisar de primeiro gerar um tarball:

    % git deborig

EDITAR O EMPACOTAMENTO DEBIAN
Apenas faça cometidos em mestre que mudem o conteúdo de debian/.

EDITAR A FILA DE ESPERA DELTA

  Adicionar novas patches
Adicionar novas patches é direto: apenas faça cometidos que mexam em apenas ficheiros fora do directório debian/. Você também pode usar ferramentas como git-revert(1), git-am(1) e git-cherry-pick(1).

  Editar patches: iniciar um debrebase
git-debrebase(1) é um envoltório em redor do git-rebase(1) que permite-nos editar, re-ordenar e apagar patches. Corra

    % git debrebase -i

para iniciar um rebase interativo. Você pode editar, re-ordenar e apagar cometidos tal como fazia durante git rebase -i.

  Editar patches: acabar um debrebase
Após completar o git rebase, o seu ramo não vai estar em avanço rápido do CABEÇALHO git que tinha antes do rebase. Isto significa que não podemos empurrar o ramo para lado nenhum. Se você está pronto para enviar, o dgit push-source (ou dgit push-built) irá tratar de corrigir isto por si.

Se você ainda não está pronto para enviar, e quer empurrar o seu ramo para um git remoto tal como salsa.debian.org,

    % git debrebase conclude

Note que cada vez que você conclui um debrebase você introduz em entrada de pseudo-fusão no seu histórico git, o que o pode tornar mais difícil de ler. Tente fazer todas as sua edições da fila delta que pensa que vão ser necessárias para esta sessão de edição num único debrebase, para que haja um único ponto do debrebase.

COMPILAR E ENVIAR
Você pode usar o dpkg-buildpackage(1) para compilações de teste. Quando estiver pronto para compilar antes de um envio, use dgit sbuild, dgit pbuilder ou dgit cowbuilder. Os envios rotineiros de apenas-fonte podem ser feitos apenas escrevendo

    % git debpush

Na primeira vez passe --quilt=linear. Isto é especialmente importante se você converteu o pacote a partir de outro fluxo de trabalho. Veja git-debpush(1).

Se você precisar de enviar para NOVO, você vai precisar de usar dgit push-built. Lembre-se de passar --new se o pacote for novo na suite alvo, e de fazer git push para salsa.debian.org depois disso.

Em alguns casos onde você usou git debrebase convert-from-gbp desde o último envio, e está a enviar com o dgit, não é possível ao dgit avançar rápido o seu histórico a partir do histórico em dgit-repos. Em tais casos você vai ter que passar --trust-changelog ao dgit. O git-debrebase irá normalmente dizer-lhe se isto vai ser preciso. (O git-debpush lida com isto de maneira transparente.)

Mesmo antes do envio, se você não o fez já, você pode querer que o git-debrebase(1) baralhe o seu ramo de modo a que a fila delta Debian apareça mesmo na ponta do ramo que vai empurrar:

    % git debrebase quick
    % git debpush

Note que isto vai introduzir uma nova pseudo-fusão.

MANUSEAR MATERIAL DFSG-NÃO-LIVRE

  Material ilegal
Aqui explicamos como lidar com material que é meramente DFSG-não-livre. Material que é legalmente perigoso (por exemplo, ficheiros que são efetivamente ilegais) não pode ser lidado desta maneira.

Se você encontrar material possivelmente-legalmente-perigoso no código fonte do autor deve procurar aconselhamento. É geralmente melhor não levantar ondas numa lista de mail pública (pelo menos, não de início). Em vez disso, mande email aos administradores do arquivo. Para Debian isso é Para: dgit-owner@debian.org, ftpmaster@ftp-master.debian.org

  DFSG-não-livre: Quando o autor lança etiquetas em git
A nossa abordagem é manter um ramo de autor DFSG-limpo, e criar etiquetas neste ramo para cada lançamento que queremos importar. Depois importamos essas etiquetas por "Importar o lançamento", em cima. No caso de um pacote novo, nós baseamos a nossa Debianização inicial na nossa etiqueta DFSG-limpa.

Para o primeiro lançamento de autor que requer filtragem DFSG:

    % git checkout -b upstream-dfsg 1.2.3
    % git rm evil.bin
    % git commit -m "upstream version 1.2.3 DFSG-cleaned"
    % git tag -s 1.2.3+dfsg
    % git checkout master

Agora ou prosseguimos com "Importar o lançamento" na etiqueta 1.2.3+dfsg, ou no caso de um pacote novo,

    % git branch --unset-upstream
    % git reset --hard 1.2.3+dfsg

e prosseguimos com "DEBIANIZAÇÃO INICIAL"

Para lançamentos subsequentes (precisem ou não de filtragem adicional):

    % git checkout upstream-dfsg
    % git merge 1.2.4
    % git rm further-evil.bin # se necessário
    % git commit -m "upstream version 1.2.4 DFSG-cleaned" # se necessário
    % git tag -s 1.2.4+dfsg
    % git checkout master
    % # proceder com "Importar o lançamento" na etiqueta 1.2.4+dfsg

O nosso ramo autor-dfsg não pode ser enviado para dgit-repos, mas como vamos precisar dele sempre que importamos uma nova versão de autor, temos de o empurrar para algum lado. Assumindo que você já configurou um remoto de origem para o em cima,

    % git push --follow-tags -u origin master upstream-dfsg

  DFSG-não-livre: Quando o autor lança apenas tarballs:
A maneira mais fácil de lidar com isto é adicionar um campo Files-Excluded a debian/copyright, e uma definição uversionmangle em debian/watch. Veja uscan(1). Em alternativa, veja a opção --filter detalhada em gbp-import-orig(1).

INCORPORAR NMUS
No caso mais simples,

    % dgit fetch
    % git merge --ff-only dgit/dgit/sid

Se isso falhar, porque o seu ramo e o trabalho de quem faz NMU representam ramos divergentes de desenvolvimento, você tem um número de opções. Aqui descrevemos as duas mais simples.

Note que você não deve tentar resolver os ramos divergentes ao editar ficheiros em debian/patches. As alterações lá ou iriam causar problemas, ou sobrescritas pelo git-debrebase(1).

  Re-basear o seu trabalho para o NMU
    % git rebase dgit/dgit/sid

Se quem fez o NMU adicionou cometidos a modificar a fonte do autor, você vai provavelmente querer fazer debrebase antes do próximo envio para arrumar as coisas.

Por exemplo, quem fez o NMU pode ter usado git-revert(1) para de-aplicar uma das suas patches. Pode ser usado um debrebase para despir ambos a patch e a reversão da fila delta.

  Aplicar manualmente o debdiff
Se não puder fazer rebase porque já empurrou para salsa.debian.org, digamos, você pode aplicar manualmente o debdiff do NMU, cometer e fazer debrebase. O próximo dgit push vai requerer --trust-changelog.

DICAS E SUGESTÕES

  Minimizar as pseudo-fusões
Em cima nós notamos que cada vez que você concluía um debrebase, você introduzia uma pseudo-fusão no seu histórico git, o que o pode tornar difícil de ler.

Uma convenção simples que pode usar para minimizar o número de pseudo-fusões é fazer git debrebase conclude apenas logo antes de enviar ou empurrar para salsa.debian.org.

É possível, apesar de muito menos conveniente, reduzir ainda mais o número de pseudo-fusões. Fazemos debrebase apenas (1) quando importamos um novo lançamento, e (2) logo antes do envio. Em vez de editar a fila delta existente, você acrescenta cometidos de correção (e reverter de cometidos) que alteram a fonte de autor para o estado requerido. Você pode empurrar para e puxar de salsa.debian.org durante isto. Mesmo antes de enviar, você faz debrebase uma vez, para arrumar tudo.

  O directório debian/patches
Neste fluxo de trabalho, debian/patches é puramente uma saída do git-debrebase(1). Você não deve fazer alterações lá. Elas irão ou causar problemas, ou serem ignoradas e sobrescritas pelo git-debrebase(1).

debian/patches vai estar muitas vezes desatualizado porque o git-debrebase(1) irá apenas regenera-lo quando precisa de o fazer. Assim você não se deve basear na informação nesse directório. Ao preparar patches para encaminhar ao autor, você deve usar git-format-patch(1) em cometidos git, em vez de enviar ficheiros de debian/patches.

  Ramos do autor
Neste fluxo de trabalho, nós especificamos etiquetas de autor em vez de quaisquer ramos.

Excepto quando (1) o autor lança apenas tarballs, (2) nós requeremos filtragem DFSG, ou (3) você também está envolvido com o desenvolvimento do autor, nós não mantemos nenhum ramo local correspondente ao autor, excepto ramos temporários usados para preparar patches para encaminhar, e coisas parecidas.

A ideia aqui é que do ponto de vista de Debian, os lançamentos do autor são pontos imutáveis na história. Nós queremos ter certeza que estamos a basear o nosso pacote Debian numa versão do autor identificada apropriadamente, em vez de qualquer cometido arbitrário em algum ramo. As etiquetas são mais úteis para isto.

Os ramos de autor continuam disponíveis como os ramos de acompanhamento do git remoto para o seu remoto de autor, ex. remotes/upstream/master.

  O primeiro dgit push de sempre
Se este é o primeiro dgit push do pacote para esta suite, considere passar --deliberately-not-fast-forward em vez de --trust-changelog. Isto evita introduzir um novo cometer de origem no seu histórico git. (Este cometer de origem iria representar o envio não-dgit mais recente do pacote, mas isto já deve estar representado no seu histórico git.)

  Inspecionar o histórico
O histórico git criado por git-debrebase pode parecer complicado. Aqui estão algumas sugestões para invocações de ajuda de gitk e git. Elas podem ser adaptadas para outras ferramentas como tig(1), git-log(1), magit, etc.

História do pacote em Debian, descartando a história do autor:

    % gitk --first-parent

    Num ramo lavado, a fila delta fica no topo.

História do empacotamento, excluindo a fila delta:

    % gitk :/debian :!/debian/patches

Apenas a fila delta (isto é, as alterações Debian à fonte do autor):

    % gitk --first-parent -- :/ :!/debian

Histórico completo incluindo versões antigas da fila delta:

    % gitk --date-order

    Os cometidos "Declara avanço rápido" que vê têm um histórico mais antigo (geralmente uma fila delta mais antiga) que um pai, e uma história mais recente que o outro. --date-order faz o gitk mostrar as filas delta na ordem certa.

Diff completo deste o último envio:

    % git diff dgit/dgit/sid..HEAD -- :/ :!/debian/patches

    Isto inclui alterações aos ficheiros do autor.

Interdiff da fila delta desde o último envio, se você realmente o quiser:

    % git debrebase make-patches
    % git diff dgit/dgit/sid..HEAD -- debian/patches

E claro existe isto:

    % git debrebase status

  Maneiras alternativas de arrancar um debrebase
Em cima nós arrancamos um debrebase interactivo ao invocar o git-debrebase(1) como isto:

    % git debrebase -i

É também possível efetuar um re-base não interactivo, como isto:

    % git debrebase -- [opções de git-rebase...]

Uma terceira alternativa é ter o git-debrebase(1) a baralhar todas as alterações Debian no fim do seu ramo, e depois manipula-los você mesmo usando o git-rebase(1) diretamente. Por exemplo,

    % git debrebase
    % git rebase -i HEAD~5      # existem 4 patches Debian

Se você tomar esta abordagem, deve ter muito cuidado de não arrancar o rebase demasiado cedo, incluindo antes da pseudo-fusão mais recente. O git-rebase sem um argumento base vai muitas vezes iniciar o rebase mito cedo, e deve ser evitado. Corra git-debrebase em vez disso. Veja também "OPERAÇÕES ILEGAIS" em git-debrebase(5).

VEJA TAMBÉM
dgit(1), dgit(7), git-debrebase(1), git-debrebase(5), gitrevisions(7)

AUTOR
Este tutorial foi escrito e é mantido por Sean Whitton <spwhitton@spwhitton.name>. Contém contributos de outros contribuidores do dgit também - veja o ficheiro copyright do dgit.