Debian git packaging maintainer branch formats and workflows
Debian maintainers use a wide variety of approaches to managing the source code for their packages. This page classifies many known git-based approaches.1
The classification is based not primarily on the tools used. Some of the formats are very tool-specific, but some (such as "unapplied") can be manipulated by a very wide variety of tools - so much so that maintainers using the same branch format and structure may have non-overlapping workflows and tooling. So, we base the classification on the format of the maintainer's git branch: its tree content, and history.
This front page of the survey is a summary of all git branch formats presently in use. The survey also contains inner pages, one for each branch format. The inner page for a branch format contains less terse descriptions of the contents of the maintainer's branch, and workflows for common package maintenance tasks for maintainers using that branch format. For example, on the inner page for the unapplied branch format you can learn that, for a maintainer using this branch format, the gbp-pq(1) tool can be used as part of a workflow for editing patches.
Users of a git branch format are encouraged to fill in the details of their workflows for common packaging tasks on the relevant inner page. The names of the branch layouts in the following table are links to the inner pages.
On this page, the dgit maintainers (who are experts in Debian's git workflows) also makes some opinionated, but hopefully helpful, observations about the various approaches. [A]
(Note on formatting: If you log into the wiki and change your style to Classic, you will get cell borders on these tables, which are desperately needed. 864925 . Additionally, in the default style, the lettered footnote A appears as a duplicate numbered footnote 1 in the list of footnotes. 931224 . Unfortunately the Classic style is not the default. 931225 .)
Name or description |
Delta representation 2 |
Tree contents 3 |
History form |
Upstream handling |
.dsc format |
Tools |
dgit push quilt mode |
Best practice workflow tutorial [A] |
Comments [A] |
||
upstream files 4 |
packaging |
d/patches |
|||||||||
d/patches |
unmodified |
complete |
yes |
any ff |
upstream tags; or tarball imports |
3.0 (quilt) |
gbp pq, git-format-patch, [d]quilt |
gbp or unapplied |
dgit-maint-gbp(7) |
Currently the dominant approach. Wide variety of tools for queue maintenance. Unfortunately, all approaches are clumsy. |
|
direct git commits, merges |
modified |
complete |
yes if 3.0 (quilt) |
any ff |
upstream tags; or tarball imports |
1.0 or single patch |
git-merge, git-commit |
n/a |
dgit-maint-merge(7) |
Good for packages with trivial delta from upstream. |
|
direct git commits, rebased |
modified |
complete |
maybe (ignored) |
git-debrebase format, usu. descended from upstream |
upstream tags; or tarball imports |
usu. 3.0 (quilt) |
git-debrebase, git-commit |
linear |
dgit-maint-debrebase(7) |
Rather new. Merges of concurrent work by multiple team members, are still experimental. |
|
direct git commits, rebased |
modified plus .git-dpm file |
complete |
yes |
git-dpm format, usu. descended from upstream |
upstream tags; or tarball imports |
usu. 3.0 (quilt) |
git-dpm |
dpm |
|
In-tree metadata vulnerable to corruption. (Are merges of concurrent work supported?) |
|
d/patches |
none |
complete |
yes |
any ff, not descended from upstream |
tarballs, perhaps from upstream git tags |
3.0 (quilt) |
gbp, git-format-patch, [d]quilt |
baredebian+git or baredebian+tarball |
|
Poor. No access to upstream git history; requires use of quilt and similar tools. |
|
.../patches |
none |
multiple packages' packaging |
yes, in multiple directories |
any ff, not descended from upstream |
usu. bespoke |
varies, often 3.0 (quilt) |
package-specific tools |
not yet supported |
README.source in package or git |
Often used by language-specific packaging teams. Sometimes even one monorepo per language, describing hundreds of source packages. |
|
d/patches |
none |
template 5 + machinery |
yes |
any ff, not descended from upstream |
tarballs, perhaps from upstream git tags; maybe bespoke |
varies, often 3.0 (quilt) |
package-specific template tools, quilt etc. |
not yet supported |
README.source in package or git |
Poor: same problems as bare debian, but also not directly buildable. |
|
direct git commits, merges |
modified |
complete |
no |
any ff, merging with upstream |
upstream tags; or tarball imports |
3.0 (quilt) |
git-merge, git-cherry-pick, git-debcherry |
not yet supported 930881 |
|
Not very widely used, but seems like a competent approach. After upstream merges, delta queue representation can degrade in quality. |
|
rebasing git branch |
modified |
complete |
? |
one topic branch per upstream version |
upstream tags; or tarball imports |
? |
git-rebase |
Not fully supported. Perhaps linear after 926640 |
|
Simple. However, non-ff branches make collaboration and publication more awkward. |
|
changes to orig plus also d/patches |
partially modified |
complete |
partial set |
complex |
varies |
usu. 3.0 (quilt) |
git-merge, git-cherry-pick, [d]quilt, etc. |
unapplied |
This approach is complex and confusing. Avoid. |
||
git commits and patches, in sync |
modified |
complete |
yes |
any ff |
upstream tags; or tarball imports |
3.0 (quilt) |
git-format-patch, dgit quilt-fixup |
nofix or linear |
|
Too much manual work in all but simple cases. 6 |
|
Footnotes
As noted in the introduction, the value judgements expressed here (eg in the columns "Best practice" and "Comments") are those of the dgit maintainers. Please do not make edits to those, unless you're confident we'll agree with you. This departure from normal wiki practice is justified in our opinion by the need to produce a useful summary. As part of our work on dgit we have encountered and researched these various approaches.
(Unfortunately, in the default wiki style, the lettered footnote A appears above as a duplicate numbered footnote 1. 931224)
This page does not discuss Debian-native packages, where there is no upstream and therefore no upstream delta to maintain/rebase/etc. (1)
We use the term "delta" for the changes made by Debian to upstream files (2)
The contents of the git tree objects in the maintainer's branch, usually master (3)
We use the term "upstream files" for the parts of the source package that are outside the debian/ directory (4)
We use "template" to mean programs and input files which together generate critical files, notably debian/control, debian/changelog or debian/rules (5)
The dgit nmu workflow is a bit like this, but dgit does the maintenance of d/patches (6)
Upstream handling
Most of the above approaches can be used either with upstream tarballs, or with upstream git tags or branches - as noted. Most of the above approaches require both a git representation of upstream, and a tarball representation.
Upstream approach name |
Upstream deliverables used by Debian maintainer |
git representation obtained how |
.orig tarball representation obtained how 1 |
Publishes upstream git history |
Comments [A] |
pure git |
git tag (from upstream, or made by maintainer) |
git tag used directly |
git-deborig (or git-archive rune) |
Yes (generally) |
Simple. Little effort spent on messing with tarballs. How free software contributors outside of Debian increasingly expect things to work. Often produces upstream-identical .orig tarballs (e.g. projects hosted in ?GitHub) but sometimes does not. |
tarball |
tarball(s) |
tarball import (git add or gbp) |
upstream tarball used directly |
No |
Requires tarballs to be passed separately for eg sponsorship. Can be awkward to switch to an unreleased-by-upstream upstream version, as upstream git often different from their tarballs. |
hybrid, identical orig |
git tag and exactly corresponding tarball |
git tag used directly |
upstream tarball used directly |
Yes |
Often accidentally turns into "hybrid with non-identical orig" due to poor release processes upstream |
hybrid, differing orig |
git tag and differing tarball 2 |
git tag used directly |
upstream tarball used directly |
Only certain differences between git and tarball are allowed; typically, files in tarball but not in git. Official source package, and maintainer's working branch, can be significantly different - ie, maintainer is publishing as official Debian source something that is not the source they use and build. Not compatible with dgit. |
Further footnotes
In the hybrid approaches, pristine-tar can be used as a way of transporting the orig tarball via git repositories. (1)
e.g. tarball contains configure, but upstream git does not (2)
The git branch contains the upstream git history, but the source package contains additional upstream files. See the Comments on this approach. (3)