NOME¶

dgit - princípios de operação

SUMÁRIO¶

O dgit trata o arquivo Debian como um sistema de controle de versão, e usa gateways bidirecionais entre o arquivo e git. A vista git do pacote pode conter o histórico git usual do autor, e será aumentado por cometidos que representam envios feitos por outros desenvolvedores que não usam o dgit. Este histórico git é guardado numa localização canónica conhecida como dgit-repos que vive num servidor git dedicado.

os ramos git apropriados para se usar com dgit podem ser editados diretamente em git, e usados diretamente para compilar pacotes binário. Eles podem ser partilhados usando todos os meios convencionais para partilhar ramos git. Não é necessário usar o dgit para trabalhar com ramos git em modo dgit. No entanto, o dgit é (geralmente) necessário de modo a converter para ou de pacotes fonte de formato Debian.

VEJA TAMBÉM¶

dgit(1)

Manual de referência e catálogo de documentação.

dgit-*(7)

Tutoriais e guias de fluxo de trabalho. Veja dgit(1) para uma lista.

MODELO¶

Você pode usar qualquer fluxo de trabalho git apropriado com o dgit, desde que satisfaça os requerimentos do dgit:

o dgit mantém um pseudo-remoto chamado dgit, com um ramo por suite. Este remoto não pode ser usado com git simples.

O repositório dgit-repos para cada pacote contém uma referência por suite chamada refs/dgit/suite. Para estes só se deve empurrar pelo dgit. São de avanço rápido Cada empurrar neste ramo corresponde a um envio (ou envio tentado).

No entanto, não há problema em ter outros ramos no dgit-repos; o repositório dgit-repos para o pacote pode até ser o mesmo que o remoto `origin', apesar de isto não ser geralmente o caso em Debian.

dgit push-* irá também fazer etiquetas assinadas chamadas archive/debian/versão (com versão codificada em DEP-14) e empurra-as para o dgit-repos. Estas são usadas no servidor para autenticar o que é empurrado.

Envios feitos pelo dgit contêm um campo adicional Dgit no pacote fonte .dsc. (Isto é adicionado por dgit push-*.) Isto especifica: um cometido (um antepassado do ramo dgit/suite) cuja árvore é idêntica ao envio de fonte desempacotada; a distribuição para a qual o envio foi feito; um nome de etiqueta que pode ser usado para ir buscar os cometidos git; e um url para usar como dica para o servidor git dgit para essa distribuição.

Os envios não feitos pelo dgit são representados em git por cometidos que são sintetizados pelo dgit. A árvore de cada tal cometido corresponde à fonte desempacotada; há um cometido com o conteúdo, e uma pseudo-fusão a partir do último envio conhecido - isto é, a partir do conteúdo do ramo dgit/suite. Dependendo do formato do pacote fonte, o cometido de conteúdo pode ter uma estrutura mais complexa, mas no final irá ser uma convergência de ramos pequeninos a partir cometidos de origem que representam os componentes do pacote fonte.

O dgit espera que as árvores com que trabalha tenham um dgit (pseudo) remoto. Isto refere-se à vista git criada por dgit do arquivo correspondente.

A vista de acompanhamento do arquivo dgit é sintetizada localmente, a pedido, por cada cópia do dgit. A vista de acompanhamento é sempre um descendente do ramo de suite dgit-repos (se um existir), mas pode estar à frente dele se foram feitos envios sem o dgit. A vista de acompanhamento do arquivo é sempre de avanço rápido dentro de cada suite.

dgit push-* pode operar em qualquer cometido que seja um descendente do ramo de acompanhamento da suite.

O dgit não faz um registo sistemático das suas importações de tarball(s) de origem. Assim não funciona ao encontrar etiquetas ou ramos git que façam referência a tarball(s) de origem. Os tarballs de origem são descarregados (por dgit clone) para o directório pai, como um fluxo de trabalho tradicional (não-à-git) do dpkg-source. Você precisa de reter estes tarballs no directório pai para o dgit build e dgit push-*. (Eles não são necessários para fluxos de trabalho puramente-baseados-em-git.)

Os repositórios dgit podiam ser clonados com métodos standard (git). No entanto, os repositórios dgit não contêm envios não feitos com dgit. E para compilações / envios de fonte abundante os tarball(s) de origem precisam estar presentes no directório pai.

Para um utilizador a olhar para um arquivo, as alterações empurradas num NMU simples a usar dgit parecem alterações razoáveis feitas num NMU: num pacote `3.0 (quilt)' o delta do envio anterior é guardado em novas patch(es) construídas pelo dpkg-source.

SUITES COMBINADAS¶

O dgit pode sintetizar uma vista combinada de várias suites subjacentes. Isto é requisitado ao especificar uma lista separada por vírgulas, por suite,:

mainsuite,subsuite...

Esta facilidade está disponível com dgit clone, apenas busca e puxa.

O dgit vai buscar o mesmo pacote de cada suite subjacente especificada, em separado (como se com dgit fetch). O dgit vai depois gerar um cometido de pseudo-fusão no ramo de acompanhamento remotes/dgit/dgit/suite o qual tem a ponta de cada uma das suites subjacentes como um antepassado, e que contem o mesmo que a suite que tiver a versão mais alta do pacote.

O pacote tem de existir na suite principal, mas não precisa existir nas sub-suites.

Se uma sub-suite especificada começar com - então é prefixado mainsuite.

Assim, por exemplo, stable,-security significa procurar o pacote em stable, e stable-security, tomando qual deles for mais recente. Se stable for atualmente trixie, o dgit clone iria deixa-lo no ramo dgit/trixie,-security.

Suites combinadas não são suportadas pelas operações de compilação do dgit. Isto porque essas opções destinam-se para compilação para enviar pacotes fonte, e procurar no registo de alterações para encontrar a suite relevante. Não faz sentido nomear uma suite combinada sintetizada pelo dgit num registo de alterações, ou tentar enviar para ela.

Ao usar esta facilidade, é importante especificar sempre as mesmas suites na mesma ordem: caso contrário o dgit não irá fazer uma vista de histórico de avanço rápido coerente.

O histórico gerado por esta funcionalidade não é normalmente apropriado para fundir de volta em autorias, pois contém necessariamente pseudo-fusões não atrativas.

LIMITAÇÕES¶

Porque a síntese dos ramos de acompanhamento de suite é feita localmente com base apenas no estado do arquivo atual, não irá necessariamente ver todos os envios não feitos com o dgit. Também, versões diferentes do dgit (ou do software que ele chama) podem importar os mesmos .dscs de maneira diferente (apesar de tentarmos minimizar isto). Como consequência, as vistas de acompanhamento do dgit da mesma suite, feita por instâncias diferentes do dgit, podem variar. Elas irão ter o mesmo conteúdo, mas podem ter um histórico diferente.

Não há nenhuma vinculação uniforme entre os ramos de acompanhamento para suites diferentes. A infraestrutura Debian não faz nenhuma importação automática dos envios feitos sem o dgit. Seria possível para uma infraestrutura de distribuição fazer isto; nesse caso, diferentes instâncias de clientes dgit iriam ver exatamente o mesmo histórico.

Não tem havido nenhuma importação a granel de envios históricos para a infraestrutura dgit de Debian. Para fazer isto seria necessário decidir se devemos importar históricos vcs existentes (que podem não ser fiéis às invariantes do dgit) ou envios não-Dgit anteriores (que não iriam fornecer um histórico muito rico).

O git representa apenas executabilidade de ficheiros. O git não representa directórios vazios, ou quaisquer objetos folha para além de ficheiros simples e links simbólicos. O comportamento dos formatos de pacote fonte Debian em objetos com permissões não usuais é complicado. Alguns pacotes fonte Debian patológicos não irão mais compilar se os directórios vazios forem podados (ou se outras coisas não reproduzidas por git forem alteradas). Tais fontes não pode ser trabalhadas de modo apropriado em git, e por isso também não com dgit.

DISTRIBUIÇÕES APENAS-LEITURA¶

Distribuições que não mantêm um conjunto de repositórios git com histórico dgit podem ainda ser usadas num modo de só-leitura com dgit. Atualmente Ubuntu está configurada desta maneira.

ATRIBUTOS DO GIT¶

O git tem funcionalidades que podem transformar ficheiros automaticamente quando estão a ser copiados entre a árvore de trabalho e o histórico git. Os atributos podem ser especificados na própria árvore fonte, em .gitattributes. Veja gitattributes(5).

Estas transformações são sensíveis ao contexto e não são, em geral, revertíveis, assim o dgit opera no principio que o histórico git do dgit contem o conteúdo atual do pacote. (Quando o dgit manipula um .dsc, fá-lo numa área privada, onde os atributos git de transformação são desarmados para se obter isto.)

Se os atributos git de transformação forem usados, eles podem causar problemas, porque os ficheiros da árvore de trabalho podem ser diferentes do histórico de revisão git (e assim dos pacotes fonte). O dgit avisa se encontrar um ficheiro .gitattributes (no pacote a ser procurado ou importado), a menos que os atributos git de transformação tenham sido desarmados.

Os dgit clone e dgit setup-new-tree desativam os atributos git de transformação por predefinição, ao criar um .git/info/attributes apropriado. Veja dgit setup-new-tree e dgit setup-gitattributes em dgit(1).

Note que o dgit não desativa os atributos git a menos que eles interfiram realmente no seu trabalho nos ramos dgit. Em particular, os atributos git que afetam git archive não são desativados, assim o .origs que você gera manualmente pode estar errado. Você deve considerar usar o git-deborig (1) que faz isto bem feito, suprimindo os atributos.

Se o autor confia em atributos git para qualquer coisa importante, você tem de reproduzir o efeito em debian/rules e/ou um caminho especifico de Debian.

FORMATOS FONTE DE PACOTE¶

Se você não é um maintainer, não precisa de se preocupar com o formato fonte do pacote. Você pode apenas fazer as alterações que quer em git. Se o pacote for um pacote `3.0 (quilt)', a pilha de patch não será geralmente representada no histórico git.

EXECUTABILIDADE DO FICHEIRO¶

Os formatos de pacote fonte Debian nem sempre reproduzem fielmente alterações para executabilidade. Mas o dgit insiste que o resultado do dgit clone seja idêntico (até onde o git consegue representar - veja Limitações, em cima) ao resultado de dpkg-source -x.

Assim os ficheiros que são executáveis na sua árvore git têm de ser executáveis no resultado de dpkg-source -x (mas muitas vezes não são). Se um pacote tem tais ficheiros problemáticos, eles têm de ser não executáveis nos ramos git compatíveis com dgit.

FORMATO 3.0 (QUILT)¶

Para um formato de pacote fonte `3.0 (quilt)', o dgit pode ter de fazer um cometido no seu ramo atual para conter metadados usados por quilt e dpkg-source.

Isto porque o formato fonte `3.0 (quilt)' representa a pilha de patch como ficheiros em debian/patches/ realmente dentro da árvore fonte. Isto significa que, tomar a árvore inteira (como visto por git ou ls) (1) o dpkg-source não pode representar certas árvores, e (2) empacotar uma árvore em `3.0 (quilt)' e depois desempacota-la nem sempre resulta na mesma árvore.

O dgit irá contornar isto automaticamente para si ao compilar e empurrar. A única coisa que precisa de saber é que dgit build, sbuild, etc., pode fazer novos cometidos no seu CABEÇALHO. Se você não for um utilizador de quilt este cometido não vai conter nenhumas alterações a ficheiros do seu interesse.

Cometer simplesmente para ficheiros fonte (seja em debian/ ou não, mas não para patches) irá resultar num ramo que o dgit quilt-fixup pode linearizar. Outro tipo de alterações, incluindo editar patches ou fundir, não pode ser lidado deste modo.

Você pode requerer explicitamente que o dgit faça apenas esta correção, ao correr dgit quilt-fixup.

Se você é um utilizador de quilt precisa de saber que as árvores git do dgit são `ramos de empacotamento de patches aplicadas' e não contêm o directório .pc (que é usado pelo quilt para gravar quais patches estão aplicadas). Se você quer manipular a pilha de patch você provavelmente vai querer olhar para ferramentas como git-debrebase, gbp pq, ou git-dpm.

dgit: base trees orig=5531f03d8456b702eab6 o+d/p=135338e9cc253cc85f84
dgit: quilt differences: src:  == orig ##     gitignores:  == orig ##
dgit: quilt differences:      HEAD ## o+d/p               HEAD ## o+d/p
starting quiltify (multiple patches, linear mode)
dgit: error: quilt fixup cannot be linear.  Stopped at:
dgit:  696c9bd5..84ae8f96: changed debian/patches/test-gitignore

VISÃO DIVIDIDA E DIVIDIR MODOS QUILT¶

Quando se trabalha com ramos git destinados a uso com o formato fonte `3.0 (quilt)' o dgit pode converter automaticamente um ramo git apropriado fornecido pelo maintainer (em um de uma variedade de formatos) num ramo dgit.

Quando é selecionado um modo quilt de dividir, os comandos de compilação do dgit e o dgit push-* irão, em cada invocação, converter o CABEÇALHO do utilizador em vista dgit, para que possa ser compilado e/ou enviado.

O modo de vista dividida também pode ser activado explicitamente com a opção de linha de comandos --split-view e a chave de configuração de acesso .split-view.

Quando a vista dividida está em operação, independentemente do modo quilt, quaisquer pseudo-fusões geradas pelo dgit e quaisquer cometidos fixup de quilt irão aparecer apenas na vista dgit. O dgit push-* vai empurrar a vista dgit para o servidor git dgit. A vista dgit é sempre um descendente da vista do maintainer. O dgit push-* vai também fazer uma etiqueta de vista de maintainer de acordo com DEP-14 e empurrar isso para o servidor git dgit.

Os modos quilt de divisão têm de ser explicitamente ativados (pelo uso das opções de linha de comandos aplicáveis, sub-comandos, ou configuração). Isto porque não é possível dizer com confiança (por exemplo) se uma árvore git para um pacote dpkg-source `3.0 (quilt)' é uma árvore de patches aplicadas ou patches não aplicadas.

Conversões de vista dividida estão guardadas em cache na referência dgit-intern/quilt-cache. Isto não deve ser manipulado diretamente.

FICHEIROS NO TARBALL ORIGINAL MAS NÃO EM GIT - AUTOTOOLS ETC.¶

Esta secção é principalmente do interesse de maintainers que querem usar o dgit com o seu histórico git existente para o pacote Debian.

Alguns desenvolvedores gostar de ter uma árvore git extra-limpa onde faltam ficheiros que normalmente são encontrados em tarballs fonte e assim em pacotes fonte Debian. Por exemplo, é convencional incluir ./configure no tarball fonte, mas algumas pessoas preferem não o ter presente na vista git do seu projeto.

O dgit requer que o pacote fonte desempacote para exatamente os mesmos ficheiros que estão no cometido git no qual o dgit push-* opera. Assim se você apenas tentar fazer dgit push-* directamente a partir de um destes ramos git extra-limpos, ele irá falhar.

Como maintainer você tem as seguintes opções:

•

Apaga os ficheiros dos seus ramos git, e os seus pacotes fonte Debian, e transporta o apagar como um delta a partir da autoria. (Com `3.0 (quilt)' isto significa representar o que é apagado com o patches. Você pode precisar de passar --include-removal ao dpkg-source --commit, ou passar opções correspondentes a outras ferramentas.) Isto torna o pacote fonte Debian menos útil para pessoas que não tenham a infraestrutura de compilação Debian.

•

Persuadis o autor que o código fonte no histórico git dele e a fonte que ele empacota como tarballs devem ser idênticos. É claro que remover simplesmente os ficheiros do tarball pode tornar o tarball difícil para pessoas usarem.

Uma resposta é cometer os ficheiros (talvez auto-gerados), talvez com alguma automatização simples para lidar com conflitos e alterações espúrias. Isto tem a vantagem de se alguém clonar o repositório git, encontra o programa tão fácil de compilar como alguém que usa o tarball.

É claro que também pode ser que as diferenças se devam a bugs do sistema de compilação, que faz com que ficheiros indesejados acabem no pacote fonte. O dgit vai avisar e queixar-se disto. Você pode ter de corrigir estes bugs antes de puder unificar o seu histórico git existente com o do dgit.

FICHEIROS NO PACOTE FONTE MAS NÃO EM GIT - DOCUMENTOS, BINÁRIOS, ETC.¶

Alguns tarballs de autor contêm artefactos de compilação que o autor espera que alguns utilizadores não desejem re-compilar (ou que achem difícil de re-compilar), mas esses tais em Debian nós os re-compilamos sempre.

Exemplos por vezes incluem binários de firmware de compilação cruzada e documentação. Para evitar problemas quando se compila pacotes fonte atualizados (em particular, para evitar tentar representar como alterações não interessantes no pacote fonte ou talvez alterações não representáveis em tais ficheiros) muitos maintainers fazem com que o alvo de limpeza do pacote apague estes ficheiros.

O dpkg-source não (com qualquer dos formatos fonte geralmente usados) representa o apagar de binários (fora de debian/) presentes na autoria. Assim apagar tais ficheiros numa árvore de trabalho do dpkg-source não resulta realmente neles a serem apagados do pacote fonte. Assim apagar os ficheiros em regras de limpeza varre este problema para baixo do tapete.

No entanto, o git recorda sempre apropriadamente o apagar de ficheiros. Como o princípio do dgit é que a árvore git do dgit é a mesma de dpkg-source -x, isso significa que uma árvore git compatível com o dgit contém sempre estes ficheiros.

Para o não-maintainer, isto pode ser observado nas seguintes ocorrências sub-ótimas:

•

O alvo de limpeza do pacote muitas vezes apaga estes ficheiros, tornando a árvore git suja ao tentar compilar o pacote fonte, etc. Isto pode ser corrigido ao usar dgit -wg aka --clean=git, para que o alvo de limpeza do pacote nunca seja executado.

•

A compilação do pacote modifica estes ficheiros, assim as compilações sujam a árvore git. Isto pode ser contornado ao se usar `git reset --hard' após cada compilação (ou pelo menos antes de cada cometido ou push).

Do ponto de vista do maintainer, a principal consequência é que para tornar um ramo git compatível com dgit é necessário cometer estes ficheiros para git. O maintainer tem algumas opções adicionais para mitigação: por exemplo, pode ser possível para o ficheiro de regras organizar para fazer a compilação numa área temporária, o que evita atualizar os ficheiros problemáticos; eles podem depois serem deixados na árvore git sem verem problemas.

PROBLEMAS COM ALVOS DE LIMPEZA DE PACOTE ETC.¶

Um problema relacionado é outro comportamento inesperado pelo alvo clean de um pacote. Se uma regra de pacote modificar ficheiros que são distribuídos no pacote, ou se simplesmente se esquecer de remover certos ficheiros, o dgit irá queixar-se que a árvore está suja.

Mais uma vez, a solução é usar dgit -wg aka --clean=git, o qual instruí o dgit a usar git clean em vez do alvo de compilação do pacote, juntamente com talvez git reset --hard antes de cada compilação.

Isto é 100% fiável, mas tem o contra que se você se esquecer de fazer git add ou de cometer, e depois usar dgit -wg ou git reset --hard, as suas alterações podem ser perdidas.