table of contents
- trixie-backports 13.15~bpo13+1
- testing 13.15
- unstable 13.15
dgit-maint-debrebase(7) | dgit | 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 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
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 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
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
Diff completo deste o último envio:
% git diff dgit/dgit/sid..HEAD -- :/ :!/debian/patches
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.
dgit+tag2upload team | Debian Project |