Translation(s): Deutsch - English - Italiano - Indonesian
Contents
Paketieren mit Git
Beachtet, dass dies eine sehr allgemeine Einführung in das Thema ist. Eine vollständige Dokumentation kann in dem git-buildpackage Paket gefunden werden (siehe online documentation).
Hilfe für die Konvertierung von Subversion Projektarchive nach Git, die mit svn-buildpackage erzeugt wurden, findet man unter the svn-buildpackage conversion subpage.
Sie sollten auch über die Unterstützung von pristine-tar weiter unten lesen.
Diese Seite beschreibt den Ablauf, der die Kommandos vom Paket git-buildpackage nutzt. Alternativ gibt es git-dpm.
Importmethode für Upstream
Es gibt 2 Hauptwege, den Upstream-Code ins debianisierte Projektarchiv zu importieren:
Man kann das Tar-Archiv des Upstream Release in ein debianspezifisches Projektarchiv importieren. In diesem wird ein Commit pro Release erstellt. Allgemein erfolgt dies mit dem gbp import-orig-Kommando. Dies ist eine grundsätzliche Methode, weil es annimmt, dass nur Upstream ein Tar-Archiv veröffentlicht.
Falls Upstream Git nutzt, um ihren Quellcode zu verwalten, kann das debianspezifisches Projektarchiv in einer Abzweigung des Haupt-Upstream-Zweiges bestehen. Offenkundig kann dies NUR bei einigen Upstream-Projekten funktionieren, aber der große Vorteil ist, dass der Zusammenhang zwischen dem debianisierten Code und dem Upstream-Code SEHR klar ist. Korrekturen und Veröffentlichungen sind viel natürlicher. Da die Debian APT Projektarchive noch Tar-Archive benutzen, muss man immer noch diese mit dieser Einrichtung bewältigen, aber es gibt für diesen Zweck pristine-tar.
Es gibt auch eine dritte Option, die eine Kombination der Beiden ist: gbp import-orig --upstream-vcs-tag. Diese Option ist in erster Linie zweckmäßig, wenn das Orig-Tar-Archiv nicht identisch ist mit dem Upstream-Veröffentlichungsetikett, was passieren kann, wenn beispielsweise
- das Tar-Archiv umgepackt wurde (z.B. um Nicht-DFSG Teile zu entfernen)
das Skript, welches Upstream benutzt, um Tar-Archive zu erzeugen, Änderungen bewirkt (das autotools make dist macht dies in einigen Projekten).
Die verschiedenen Vor- und Nachteile werden hier diskutiert:
Anfangen
Upstream als Tar-Archiv importieren
Es ist sehr einfach, die erste Version eines Paketes zunächst außerhalb von Git zu erstellen. Wenn dies einmal getan ist, sollte man das Paket unter Benutzung des Befehls import-dsc des gbp-Werkzeuges importieren. Früher war dies git-import-dsc. Das Verzeichnis, in dem der Befehl aufgerufen wurde, wird das Eltern-Verzeichnis des neuen Git Projektarchives werden.
$ gbp import-dsc /path/to/package_0.1-1.dsc
Der Fortschritt wird ausgegeben, und es werden einige Commits erzeugt. Anschließend gibt es einige neue Dateien und Verzeichnisse:
$ ls package/ package_0.1-1.orig.tar.gz
Ein Blick in das neue Projektarchiv zeigt, dass git-buildpackage folgendes gemacht hat:
Es importierte die Dateien des Paketes (aber nicht das debian/-Verzeichnis) in den upstream-Zweig
Dieser wurde mit dem Tag upstream/0.1 markiert, wobei 0.1 die Versionsnummer des Paketes ist.
Es importierte sowohl das debian/-Verzeichnis als auch die Upstream-Dateien in den master-Zweig
Markierte den letzten Commit als debian/0.1-1, sowie es übernommen wird, wenn das Paketieren beendet ist.
Das Upstream Projektarchiv nutzen
Wenn Upstream bereits Git nutzt, erzeugt man einfach einen Zweig für die Debianisierung. Das Übereinkommen für die Benamung der Zweige und Markierungen, sind wie im gerade beschriebenen Fall, so dass man den master-Zweig von der upstream-Veröffentlichung abtrennen und das debian/-Verzeichnis als einen Commit hinzufügen kann.
Weiterer Paketierworkflow
Nun kann man im master-Zweig arbeiten und das Paket bearbeiten. Commit mit:
$ git commit -a
und baue das Paket mit:
$ gbp buildpackage
Wenn Sie ein fertiges Paket für eine Veröffentlichung erstellt haben, markiere es auf folgende Weise:
$ gbp buildpackage --git-tag
Stelle sicher, dass die debian/changelog-Datei so korrekt ist, dass sie zur Erstellung der Markierung benutzt werden kann. Die Markierung wird debian/0.1-2 genannt, wobei 0.1-2 die Debian-Version ist.
Debian-Korrekturen handhaben
Das gbp-pq Werkzeug kann genutzt werden, um die Korrekturen in Git aufzuzeichnen und sie von und in die Quilt Serien in debian/patches zu im- und exportieren.
Auf eine neue Upstream Version aktualisieren
Import Upstream als Tar-Archiv
Wenn eine neue Upstream Version veröffentlicht wird, nutze das Kommando import-orig und füge es dem Projektarchiv hinzu. Vorher war dies git-import-orig.
Nutzung einer debian/watch Datei (empfohlen)
$ gbp import-orig --uscan
Nutzung einer Tar-Archiv Datei
$ gbp import-orig /path/to/new-upstream.tar.gz -u 0.2
wobei 0.2 die neue Upstream Versionsnummer ist.
Wenn das Upstream Tar-Archiv bereits in der Form Paketname_Version.orig.tar.gz (Z.B. package_0.2.orig.tar.gz) vorliegt, dann wird die -u Option nicht benötigt.
Nutzung des Upstream Paketarchivs
If we're using the upstream repo, we can git fetch the new release tag into the repo, in the upstream branch. We need to git merge this branch into master, and to commit the new tarball with pristine-tar. The patches can be rebased with gbp-pq, and git itself can be used to resolve any conflicts that have been created.
Merging a debian-experimental branch into master for sid
Lets assume you have have the following branches:
upstream |
latest upstream in development |
upstream-1.5 |
upstream's 1.5 series, considered stable |
master |
branch for building packages for sid |
debian-experimental |
branch for building packages for experimental |
- You are importing each point release into upstream-1.5 and merging to master
- You are merging each beta release (1.6~beta) into upstream and merging to debian-experimental
At some point, you want to move the work from debian-experimental to the master branch and release it to unstable.
First, it is necessary to make sure debian-experimental has everything correct in debian/* - maybe you committed something on master and didn't cherry-pick it to debian-experimental. You can compare the debian/ subtrees like this:
git checkout master git diff debian-experimental debian
If necessary, cherry pick any changes onto debian-experimental. The next merge will obliterate everything on master and replace it with the contents of the debian-experimental branch. The only thing that is kept is debian/changelog because it needs to reflect the change history within sid and does not need to contain details of individual releases to experimental. Here is how we do it (make sure master is a clean workspace):
git checkout master git clean -fd && git checkout . git merge -s ours debian-experimental git diff --binary debian-experimental | git apply -R --index git reset debian/changelog git checkout debian/changelog git commit -m 'Merge 1.6.0~rc1 from debian-experimental' --amend
After doing this, it is strongly suggested that you inspect the merge with gitk and with git diff before you push to alioth or any other developer. For example,
git diff debian-experimental
invoked in master should only show the changelog, because everything else on master should now be identical to debian-experimental.
Conclusion
That is all to the basics of building packages with Git! I would recommend making copies of packages and trying out the tools on temporary repositories, to start with. Once you feel you have mastered it, there are other options that should be looked at.
Further options
pbuilder
To use pbuilder, you must simply change builder in either ~/.gbp.conf or /etc/git-buildpackage/gbp.conf to /usr/bin/git-pbuilder
/usr/bin/git-pbuilder can be edited to use additional options, such as --builddir and --debsign-k...
Signing tags
On calling either of the git-import-dsc or git-import-orig tools, the following options may be used:
--sign-tags
- Whether to sign tags
--keyid=gpg-keyid
- With what gpg key to sign tags with
pristine-tar
git-buildpackage also supports the use of pristine-tar, a new tool developed by Joey Hess to recreate identical tarballs from a small delta file and the files in the current directory.
If you enable pristine-tar, delta files are committed to a pristine-tar branch if you call git-import-dsc or git-import-orig. When you build the package using gbp buildpackage, the exact tarball is regenerated using pristine-tar.
On calling either of the git-import-dsc or git-import-orig tools, the --pristine-tar option may be used. On calling gbp buildpackage, the --git-pristine-tar option may be used. You may also enable the pristine-tar option /etc/git-buildpackage/gbp.conf.
running lintian after the build
Add this to ~/.gbp.conf :
postbuild = lintian -I $GBP_CHANGES_FILE && echo "Lintian OK"
running autopkgtest after the build
First configure an environment for adt (see autopkgtest docs, man adt-run) Then add this to your ~/.gbp.conf :
postbuild = adt-run --changes $GBP_CHANGES_FILE --- schroot sid-amd64-sbuild; [ $? -eq 0 -o $? -eq 8 ]
The last check is there to avoid failure when there are no tests to run.
An example gbp.conf
[DEFAULT]
builder = git-pbuilder
cleaner = fakeroot debian/rules clean
# Create pristine-tar on import
pristine-tar = True
# Run lintian to check package after build
postbuild = lintian -iIE --pedantic $GBP_CHANGES_FILE && echo "Lintian OK"""
[buildpackage]
export-dir = ../build-area/
[import-orig]
# Filter out unwanted files/dirs from upstream
filter = [
'*egg.info',
'.bzr',
'.hg',
'.hgtags',
'.svn',
'CVS',
'*/debian/*',
'debian/*'
]
# filter the files out of the tarball passed to pristine-tar
filter-pristine-tar = True
[import-dsc]
filter = [
'CVS',
'.cvsignore',
'.hg',
'.hgignore',
'.bzr',
'.bzrignore',
'.gitignore'
]
[dch]
# ignore merge commit messages
git-log = --no-merges
See also
?Using Git on Alioth
- /usr/share/doc/git-buildpackage
cowbuilder and git-pbuilder may also be useful
External Links
Git homepage
Git wiki
Git manual
Using Git for Debian Packaging by Russ Allbery
discussion on how to include the upstream git in the package's git
Co-maintaining a Debian package with git, git-buildpackage and pbuilder by Philipp Huebner