Contents
- Summary
-
FAQ
- Does a 3.0 (quilt) source package need to build-depend on quilt?
- Is the README.source file needed with 3.0 (quilt) source packages?
- How to use multiple upstream tarballs in 3.0 (quilt) format?
- Why should I use 3.0 (quilt) format for my package?
- My 3.0 (quilt) package fails to build or fails to unpack on all buildds
- Why aren't -p0 patch supported in 3.0 (quilt) format?
- How many packages have already been converted?
- Are there docs?
- Are there more docs?
- Are there plans for a 4.0 format? Will I need to switch again soon?
- How to convert back to 1.0?
- Can I avoid the multiple patches? All my patches are in version control
- How to convert a source package?
- Validation of all tools with new source formats
- Contributors
Summary
This page summarizes information concerning the "3.0 (quilt)" and "3.0 (native)" source package formats that have become the de-facto standard for non-trivial packages in Debian. dpkg-source(1) recommends using one of those formats for new packages. All packages should explicitly declare their source format in debian/source/format (the default is still "1.0" which should not be used for new packages).
The 3.0 formats support
- gzip, bzip2, lzma and xz
- Note: ftp-master.debian.org may disallow formats (such as lzma) that the packaging software supports.
multiple upstream tarballs (only for the 3.0 (quilt format).
- inclusion of binary files. There is no need, for example, to uuencode a Debian specific PNG icon.
The debian directory is automatically removed from the upstream tarball. It is not necessary to repack upstream sources just because they contain a debian directory.
Debian-specific changes are stored in multiple patches in debian/patches/. This is often called a patch queue. It is compatible with quilt (hence its name) but does not require its usage as dpkg-source is able to do everything needed by itself. It applies patches at extraction time and update the patch series at build time.
These source formats are supported in Debian since the early 2010 years. You can expect universal support.
dpkg-source(1) has some documentation about all source formats in the "SOURCE PACKAGE FORMATS" chapter.
FAQ
Does a 3.0 (quilt) source package need to build-depend on quilt?
No. Don't invoke quilt explicitly in debian/rules. You CAN optionally use quilt to maintain your patch queue in debian/patches, but there are tools like gbp pq that allow you to maintain your patch queue without quilt.
Is the README.source file needed with 3.0 (quilt) source packages?
No. It's the de facto default, people know how to handle this type of package.
How to use multiple upstream tarballs in 3.0 (quilt) format?
Simply put a file <source>_<version>.orig-<addon>.tar.{gz,bz2,lzma,xz} near the traditional .orig tarball. The content of that tarball should also be already unpacked in the addon subdir of the unpacked source package. The next dpkg-source -b will pick it up automatically.
More docs can be found in this article: How to use multiple upstream tarballs in Debian source packages and in dpkg-source(1).
Why should I use 3.0 (quilt) format for my package?
Pick the reasons that matter to you:
- it's the de-facto standard, recommended by dpkg, and everyone knows how to use this format.
it keeps patches separate from each other and properly documented (with DEP-3):
- the Debian changes are more likely to be reviewed
- upstream contributors are more likely to find and merge the patches (if you haven't forwarded them properly)
- other distributions can reuse (or ignore) our patches
- even if you don't have any upstream patch right now, next time that someone must NMU your package, they can cleanly add a patch (with a proper DEP-3 header) without having to modify the build system
- same applies for derivative distributions that have to modify your packages... you're more likely to be able to find something valuable to merge
- debian/rules is simpler without patching/unpatching code
- it is easier to add binary Debian-specific data
- the upstream tarball can be compressed with other compressors than gzip while keeping pristine upstream sources in Debian's archive.
- the upstream tarball can contain a debian directory without bothering your work.
- the upstream author releases the software in multiple tarballs
My 3.0 (quilt) package fails to build or fails to unpack on all buildds
If you get a failure like:
dpkg-source: info: applying XXXX 1 out of 1 hunk FAILED -- saving rejects to file xxx.rej
You probably have quilt patches that only applies with fuzz (i.e. they only apply if patch ignores context lines). quilt applies those without failing but dpkg-source doesn't. The solution is to refresh the patches, for example with those commands :
quilt pop -a while quilt push; do quilt refresh -p ab; done
If you use gbp pq or a similar tool to maintain your patch queue, use their mechanisms.
dpkg-dev prevents you from building source packages with such patches.
Why aren't -p0 patch supported in 3.0 (quilt) format?
See sub-thread starting here.
How many packages have already been converted?
Many. Less than 5 % of Debian's source packages are not in 3.0 (quilt) format.
Are there docs?
To actually take advantage of this new format, see
the Guide for Debian Maintainers, and
Raphaël's very helpful article: How to use quilt to manage patches in Debian packages (August 8, 2012).
They explain how to add and edit patches and integrate things in your workflow.
Are there more docs?
Try:
Raphaël's Article about maintainer 3.0 quilt packages in a VCS and
Colin Watson's Article about how he uses 3.0 quilt with bzr with patches applied in bzr
Are there plans for a 4.0 format? Will I need to switch again soon?
At the time of this writing (2025/05), there are no immediate plans for a 4.0 format. But there are lists of grievances with the 3.0 formats that might be the base for future formats (such as Teams/Dpkg/TimeTravelFixes#dsc, and some of the items in Teams/Dpkg/Spec/ChangesFormat2.0 related to digests).
How to convert back to 1.0?
Please consider not doing so. We have no idea why you should want this, but DpkgV3toV1 has the instructions from the old backports.org site.
Can I avoid the multiple patches? All my patches are in version control
Yes. Just create a file debian/source/local-options with content:
single-debian-patch
This option creates a single "debian-changes" patch in debian/patches, similar to the .diff.gz of the v1 source format. The local-options file is *not* shipped with the source package, so this means that any NMUs or downstream changes will still use a separate patch file. This is a feature, not a bug; it allows you to use your preferred workflow while not impacting others.
How to convert a source package?
You need to put "3.0 (quilt)" or "3.0 (native)" in debian/source/format to indicate the desired format to dpkg-source (see dpkg-source(1) for more information):
mkdir debian/source ; echo '3.0 (quilt)' > debian/source/format ; dch 'Switch to dpkg-source 3.0 (quilt) format'
Native packages should not need any other change.
When you switch to "3.0 (quilt)", there are other changes that you might want to do:
If your .diff.gz modifies upstream files, you should really put those changes in separate quilt patches first, otherwise all those changes will be merged in a single quilt patch named debian/patches/debian-changes-<version>. Consider documenting those patches by following DEP-3.
If you use another patch system (dpatch, dbs, cdbs, etc.; with -p0, -p1, or p2), consider switching to the "3.0 (quilt)" format (see 581186 for a conversion helper script). (You can then simplify your debian/rules with "dh $@", see next point).
You should remove everything related to quilt in debian/rules (patch/unpatch logic, cleanup of quilt stamp file and its .pc directory).
Validation of all tools with new source formats
For all applications that work with 3.0 packages, please be sure to test the 3 important cases:
- 3.0 (native)
- 3.0 (quilt)
- 3.0 (quilt) with multiple upstream tarballs
It's also interesting to test with various compressions methods (gz, bz2, lzma, xz).
Some sample source packages are available here. You can add it to /etc/apt/sources.list with deb-src http://people.debian.org/~hertzog/packages/ debsrc3.0/. They have the following characteristics:
- sample1: 3.0 (quilt) with orig.tar.gz / debian.tar.gz and additional tarballs with all compressions schemes
- sample2: 3.0 (quilt) with orig.tar.bz2 / debian.tar.bz2
- sample3: 3.0 (quilt) with orig.tar.lzma / debian.tar.lzma
- sample4: 3.0 (native) with tar.gz
- sample5: 3.0 (native) with tar.bz2
- sample6: 3.0 (native) with tar.lzma
Please consider also testing with more current packages from the archive. (Contributors, please consider adding example packages here).
Current test results:
As of 2025, none of the mainstream tools that handle source packages have known issues with 3.0 packages.
Possible improvements (please consider research or asking on -devel before spending work on those, those ideas are a decade old):
- other devscripts tools ?
A new debreview tool would be welcome to replace zless *.diff.gz: 575394
- devscripts dquilt
Wishlist: wrapper for quilt. 624556
Please try using new source packages with all your usual tools (in particular if you maintain them) and file bugs if you encounter problems and usertag them appropriately (user hertzog@debian.org / tag 3.0-quilt-by-default). Also update the list above with any relevant information (including pointers to bugs).
Contributors
RaphaelHertzog and others.
CategorySpec CategoryDeveloper CategoryPackaging CategoryPermalink