| 第11章 Packaging with git | ||
|---|---|---|
 |
 |
|
| 第11章 Packaging with git | ||
|---|---|---|
| |
|
|
目次
Up to 「10章上級パッケージング」, 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.)
![[注記]](images/note.png) | 注記 |
|---|---|
|
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.
gbp(1) and its subcommands:
dgit(1) and its subcommands:
It is highly desirable to host Debian source code package on Salsa. Over 90% of all Debian source code packages are hosted on Salsa. [21]
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.:
[debhello] $ git remote add upstreamvcs <url-upstream-git-repo> [debhello] $ git fetch upstreamvcs 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 source tree matches extracted contents by 「dpkg-source -x --skip-patches」 of the Debian source package.
This repository style is useful for all variants of traditional workflows and gbp based workflow:
「「Patch by 「diff -u」 approach」」
Use helper scripts such as dquilt(1) and gbp-pq(1) to manage data in debian/patches/* files.
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 use .pc/* files to track patch state, but instead gbp-pq utilizes temporary branches in git.
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:
[debhello] $ git checkout master [debhello] $ gbp pq import gbp:info: ... imported on 'patch-queue/master [debhello] $ vim buggy_file ... [debhello] $ git add buggy_file [debhello] $ git commit [debhello] $ gbp pq export gbp:info: On 'patch-queue/master', switching to 'master' gbp:info: Generating patches from git (master..patch-queue/master) [debhello] $ git add debian/patches/* [debhello] $ dch -i [debhello] $ git commit -a -m "Closes: #<bug_number>" [debhello] $ git tag debian/<version>-<rev>
Drop (== disable) an existing patch
Refresh debian/patches/* files to make 「dpkg-source -b」 work as expected after updating a Debian package to the new upstream release.
[debhello] $ git checkout master [debhello] $ gbp pq --force import # ensure patch-queue/master branch gbp:info: ... imported on 'patch-queue/master [debhello] $ git checkout master [debhello] $ gbp import-orig --pristine-tar --uscan ... gbp:info: Successfully imported version ?.?.? of ../packagename_?.?.?.orig.tar.xz [debhello] $ gbp pq rebase ... resolve conflicts and commit to patch-queue/master branch [debhello] $ gbp pq export gbp:info: On 'patch-queue/master', switching to 'master' gbp:info: Generating patches from git (master..patch-queue/master) [debhello] $ git add debian/patches [debhello] $ git commit -m "Update patches" [debhello] $ dch -v <newversion>-1 [debhello] $ git commit -a -m "release <newversion>-1" [debhello] $ 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.
[debhello] $ gbp import-dscs --debsnap --pristine-tar <source-package>
The gbp command is provided by the git-buildpackage package.
Use 「gbp import-orig」 to import the new upstream tar to the git repository.
Use 「gbp buildpackage」 to build the Debian binary package from the git repository.
Package history management with the git-buildpackage package is becoming the standard practice for many Debian maintainers. See more at:
The gitk command in the gitk package displays changes in a repository or a selected set of commits. This includes visualizing the commit graph, showing information related to each commit, and the files in the trees of each revision.
This gitk command also provides very intuitive UI to many cumbersome operations of the 「git」 command such as 「git checkout …」, 「git reset* …」, 「git diff …」, etc..
When your local Git commit history becomes intertwined, you need to organize it before pushing it out to the public.
The most simple organization process is to squash all changes to a single commit using 「git rebase -i」 interactively.
But this may create a huge commit with files such as auto-generated files not intended to be committed. You can drop such files in the commit using 「git rm some_file」 and 「git commit --amend」. This may be quite cumbersome.
This cumbersome drop process can be eased by using the 「git-ime」 command in the imediff package. It automatically splits a single commit with many files into multiple commits involving only a single file changes. Now you can drop such files using 「git rebase -i」 interactively.
![[ヒント]](images/tip.png) | ヒント |
|---|---|
|
The 「git-ime」 operating on a single file change commit splits it into multiple commits of line changes using imediff interactively. Invoking this with the --auto option will automate this split commit operation. See git-ime(1) and imediff(1). |
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:
Organize its source tree almost like native Debian package (see 「「ネイティブ Debian パッケージ」」) with debian/* files with a few exceptions:
Generate missing upstream tarball preferably without debian/* files.
The rest is the same as the non-native packaging workflow as written in 「「Packaging workflow」」.
Although this can be done in many ways, you can use the Git repository and 「git deborig」 as:
[~] $ cd /path/to/debhello [debhello] $ dch -r ... set its <version>-<revision>, e.g., 1.0-1 [debhello] $ git tag -s debian/1.0-1 [debhello] $ git rm -rf debian [debhello] $ git tag -s upstream/1.0 [debhello] $ git commit -m upstream/1.0 [debhello] $ git reset --hard HEAD^ [debhello] $ git deborig [debhello] $ sbuild
| 注記 |
|---|---|
|
The focus of this introductory tutorial 「Guide for Debian Maintainers」 isn’t the patch applied Git repository which is rather a new trend initiated by the proponent of the dgit command. So minimal explanation is given here. |
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 dgit command is provided by the dgit package.
This command offers tools to manage Debian packaging activities mainly using 「「Patch applied Git repository」」.
| ヒント |
|---|---|
|
The dgit server is browsable at https://browse.dgit.debian.org/ site. |
| 注記 |
|---|---|
|
In order to keep the working tree dgit-compatible, delete debian/source/local-options and debian/source/local-patch-header if they exist. |
Hints for workflow styles:
dgit-maint-merge(7) workflow.
Use this for the Debian non-native package without granular topic patches recorded in the Debian source package.
Add auto-commit and single-debian-patch lines in the debian/source/options file
dgit-maint-debrebase(7) workflow.
dgit-maint-native(7) workflow,
dgit-maint-gbp(7) workflow
This author likes this new dgit command and just started to use it with dgit-maint-merge(7) and dgit-maint-native(7) workflows. Thus, topics around dgit are beyond this tutorial document to cover in depth. Please start reading the latest relevant manpages and upstream resources:
| |
|
|
| 第10章 上級パッケージング |
|
第12章 Tips |