第10章 Packaging with git

目次

10.1. Salsa repository
10.2. Salsa account setup
10.3. Salsa CI service
10.4. Branch names
10.5. Patch unapplied Git repository
10.6. Patch applied Git repository
10.7. Note on gbp
10.8. Note on dgit
10.9. Patch by gbp-pq approach
10.10. Manage patch queue with gbp-pq
10.11. gbp import-dscs --debsnap
10.12. Note on dgit-maint-debrebase workflow
10.13. Quasi-native Debian packaging

Up to 9章上級パッケージング, we focused on packaging operations without using Git or any other VCS. These traditional packaging operations were based on the tarball released by the upstream as mentioned in 「Historical perspective」.

Currently, the git(1) command is the de-facto platform for the VCS tool and is the essential part of both upstream development and Debian packaging activities. (See Debian wiki Debian git packaging maintainer branch formats and workflows for existing VCS workflows.)

[注記]注記

Since the non-native Debian source package uses diff -u as its backend technology for the maintainer modification, it can’t represent modification involving symlink, file permissions, nor binary data (March 2022 discussion on [email protected]). Please avoid making such maintainer modifications even though these can be recorded in the Git repository.

Since VCS workflows are complicated topic and there are many practice styles, I only touch on some key points with minimal information, here.

Salsa is the remote Git repository service with associated tools. It offers the collaboration platform for Debian packaging activities using a custom GitLab application instance. See:

There are 2 styles of branch names for the Git repository used for the packaging. See 「Branch names」.

There are 2 main usage styles for the Git repository for the packaging. See:

There are 2 notable Debian packaging tools for the Git repository for the packaging.

It is highly desirable to host Debian source code package on Salsa. Over 90% of all Debian source code packages are hosted on Salsa. [20]

The exact VCS repository hosting an existing Debian source code package can be identified by a metadata field Vcs-* which can be viewed with the apt-cache showsrc <package-name> command.

After signing up for an account on Salsa, make sure that the following pages have the same e-mail address and GPG keys you have configured to be used with Debian, as well as your SSH key:

Salsa runs Salsa CI service as an instance of GitLab CI for 「Continuous integration」.

For every git push instances, tests which mimic tests run on the official Debian package service can be run by setting Salsa CI configuration file debian/salsa-ci.yml file」 as:

---
include:
  - https://salsa.debian.org/salsa-ci-team/pipeline/raw/master/recipes/debian.yml

# Customizations here

The Git repository for the Debian packaging should have at least 2 branches:

In this tutorial, old style branch names are used in examples for simplicity.

[注記]注記

This upstream-branch may need to be created using the tarball released by the upstream independent of the upstream Git repository since it tends to contain automatically generated files.

The upstream Git repository content can co-exit in the local Git repository used for the Debian packaging by adding its copy. E.g.:

$ git remote add upstream-git <url-upstream-git-repo>
$ git fetch upstream-git master:upstream-master

This allows easy cherry-picking from the upstream Git repository for bug fixes.

The patch unapplied Git repository can be summarized as:

[注記]注記

The debian/source/local-options and debian/source/local-patch-header files are meant to be recorded by the git command. These aren’t included in the Debian source package.

The patch applied Git repository can be summarized as:

  • The source tree matches extracted contents by dpkg-source -x of the Debian source package.

    • The source tree is buildable and the same as what NMU maintainers see.
    • The source is recorded in the Git repository with maintainer changes including the debian/ directory.
    • Maintainer changes to the upstream source are also recorded in debian/patches/* files for the Debian source format 3.0 (quilt).

Use one of workflow styles:

The gbp command is provided by the git-buildpackage package.

  • This command is designed to manage contents of 「Patch unapplied Git repository」」 efficiently.
  • Use gbp import-orig to import the new upstream tar to the git repository.

    • The --pristine-tar option for the git import-orig command enables storing the upstream tarball in the same git repository.
    • The --uscan option as the last argument of the gbp import-orig command enables downloading and committing the new upstream tarball into the git repository.
  • Use gbp import-dsc to import the previous Debian source package to the git repository.
  • Use gbp dch to generate the Debian changelog from the git commit messages.
  • Use gbp buildpackage to build the Debian binary package from the git repository.

    • The sbuild package can be used as its clean chroot build backend either by configuration or adding --git-builder='sbuild -A -s --source-only-changes -v -d unstable'
  • Use gbp pull to update the debian, upstream and pristine-tar branches safely from the remote repository.
  • Use gbp pq to manage quilt patches without using dquilt command.
  • Use gbp clone REPOSITORY_URL to clone and set up tracking branches for debian, upstream and pristine-tar.

Package history management with the git-buildpackage package is becoming the standard practice for many Debian maintainers. See more at:

The dgit command is provided by the dgit package.

The new dgit package offers commands to automate packaging activities using the git repository as an alternative to still popular gbp-buildpackage. Please read their guide:

  • dgit-maint-merge(7) — for the Debian source format 3.0 (quilt) package with its changes flowing both ways between the upstream Git repository and the Debian Git repository which are tightly coupled using 「Patch applied Git repository」.
  • dgit-maint-debrebase(7) — for the Debian source format 3.0 (quilt) package with its changes flowing mostly one way from the upstream Git repository to the Debian Git repository using 「Patch applied Git repository」.
  • dgit-maint-gbp(7) — for the Debian source format 3.0 (quilt) package with its Debian Git repository which is kept usable also for people using gbp-buildpackage(1) using 「Patch unapplied Git repository」.
  • dgit-maint-native(7) — for the Debian source format 3.0 (native) package in the Debian Git repository. (No maintainer changes)

The dgit(1) command can push the easy-to-trace change history to the https://browse.dgit.debian.org/ site and can upload Debian package to the Debian repository properly without using dput(1).

The concept around dgit is beyond this tutorial document. Please start reading relevant information:

For 「Patch unapplied Git repository」」, you can generate debian/patches/* files using the gbp-pq(1) command from git commits in the through-away patch-queue branch.

Unlike dquilt which offers similar functionality as seen 「Patch by dquilt approach」 and 「Manage patch queue with dquilt, gbp-pq doesn’t generate .pc/* files.

You can add, drop, and refresh debian/patches/* files with gbp-pq to manage patch queue.

If the package is managed in 「Patch unapplied Git repository」」 using the git-buildpackage package, you can revise the upstream source to fix bug as the maintainer and release a new Debian revision using gbp pq.

  • Add a new patch recording the upstream source modification on the file buggy_file as:

     $ git checkout master
     $ gbp pq import
    gbp:info: ... imported on 'patch-queue/master
     $ vim buggy_file
      ...
     $ git add buggy_file
     $ git commit
     $ gbp pq export
    gbp:info: On 'patch-queue/master', switching to 'master'
    gbp:info: Generating patches from git (master..patch-queue/master)
     $ git add debian/patches/*
     $ dch -i
     $ git commit -a -m "Closes: #<bug_number>"
     $ git tag debian/<version>-<rev>
  • Drop (== disable) an existing patch

    • Comment out pertinent line in debian/patches/series
    • Erase the patch itself (optional)
  • Refresh debian/patches/* files to make dpkg-source -b work as expected after updating a Debian package to the new upstream release.

     $ git checkout master
     $ gbp pq --force import # ensure patch-queue/master branch
    gbp:info: ... imported on 'patch-queue/master
     $ git checkout master
     $ gbp import-orig --pristine-tar --uscan
      ...
    gbp:info: Successfully imported version ?.?.? of ../packagename_?.?.?.orig.tar.gz
     $ gbp pq rebase
     ... resolve conflicts and commit to patch-queue/master branch
     $ gbp pq export
    gbp:info: On 'patch-queue/master', switching to 'master'
    gbp:info: Generating patches from git (master..patch-queue/master)
     $ git add debian/patches
     $ git commit -m "Update patches"
     $ dch -v <newversion>-1
     $ git commit -a -m "release <newversion>-1"
     $ git tag debian/<newversion>-1

For Debian source packages named <source-package> recorded in the snapshot.debian.org archive, an initial git repository managed in 「Patch unapplied Git repository」 with all of the Debian version history can be generated as follows.

$ gbp import-dscs --debsnap --pristine-tar <source-package>

Here are some hints around dgit-maint-debrebase(7). [21]

  • Use dgit setup-new-tree to prepare the local git working repository.
  • The first maintainer modification commit should contain files only in the debian/ directory excluding files in the debian/patches directory.
  • debian/patches/* files are generated from the maintainer modification commit history using the dgit quilt-fixup command automatically invoked from dgit build and dgit push.
  • Use git-debrebase new-version <new-version-tag> to rebase the maintainer modification commit history with automatically updated debian/changelog.
  • Use git-debrebase conclude to make a new pseudomerge (== git merge -s ours) to record Debian package with clean ff-history.

See dgit-maint-debrebase(7), dgit(1) and git-debrebase(1) for more.

The quasi-native packaging scheme packages a source without the real upstream tarball using the non-native package format.

[ヒント]ヒント

Some people promote this quasi-native packaging scheme even for programs written only for Debian since it helps to ease communication with the downstream distros such as Ubuntu for bug fixes etc.

This quasi-native packaging scheme involves 2 preparation steps:

The rest is the same as the non-native packaging workflow as written in 「Packaging workflow」.

Although this can be done in many ways (「Snapshot upstream tarball (-d, -t)」), you can use the Git repository and git deborig as:

 $ cd /path/to/<dirname>
 $ dch -r
  ... set its <version>-<revision>, e.g., 1.0-1
 $ git tag -s debian/1.0-1
 $ git rm -rf debian
 $ git tag -s upstream/1.0
 $ git commit -m upstream/1.0
 $ git reset --hard HEAD^
 $ git deborig
 $ sbuild


[20] Use of git.debian.org or alioth.debian.org are deprecated now.

[21] I may be incorrect, here.