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

unapplied

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.

merging

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.

git-debrebase

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.

git-dpm

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?)

bare debian

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.

bare debian monorepo

.../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.

bare template

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.

git-debcherry

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

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.

modified orig plus further unapplied patches

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.

manually maintained applied

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

  1. 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)

  1. This page does not discuss Debian-native packages, where there is no upstream and therefore no upstream delta to maintain/rebase/etc. (1)

  2. We use the term "delta" for the changes made by Debian to upstream files (2)

  3. The contents of the git tree objects in the maintainer's branch, usually master (3)

  4. We use the term "upstream files" for the parts of the source package that are outside the debian/ directory (4)

  5. We use "template" to mean programs and input files which together generate critical files, notably debian/control, debian/changelog or debian/rules (5)

  6. 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

Yes, misleadingly3 [A]

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

  1. In the hybrid approaches, pristine-tar can be used as a way of transporting the orig tarball via git repositories. (1)

  2. e.g. tarball contains configure, but upstream git does not (2)

  3. The git branch contains the upstream git history, but the source package contains additional upstream files. See the Comments on this approach. (3)