Provided by: dgit_13.15_all 
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 o
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 estas série de cometidos git aparecem no fim
do ramo. Todo o histórico git público é avançado-rápido, isto é, não 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.
• Benefit from dgit's safety catches. In particular, ensure that your upload always matches exactly
your git HEAD.
• 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 branch --unset-upstream
O comando final desanexa 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. Para manter uma cópia do seu ramo de empacotamento em
salsa.debian.org adicionalmente a dgit-repos, você pode fazer algo como isto:
% git remote add -f origin git@salsa.debian.org:debian/foo.git
% git push --follow-tags -u origin master
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
para um envio, use dgit sbuild, dgit pbuilder ou dgit cowbuilder.
Enviar com dgit push-source ou dgit push-built. Lembre-se de passar --new se o pacote for novo na suite
alvo.
Em alguns casos onde você usou git debrebase convert-from-gbp desde o último envio, 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.
Se você quer enviar com o git-debpush(1), para o primeiro envio você deve passar a opção de modo quilt
--quilt=linear (veja git-debpush(1)).
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
% dgit push-source
Note que isto vai introduzir uma nova pseudo-fusão.
Após o empurrar do dgit, certifique de fazer git push para salsa.debian.org, se estiver a usar isso.
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 efectivamente 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 reversões 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.
Debian Project dgit+tag2upload team dgit-maint-debrebase(7)