How Quilt Manages Patches in Debian Packages

In the Debian operating system, packaging relies on keeping upstream source code pristine while maintaining distribution-specific modifications separately. The quilt tool serves as the standard patch management system for Debian's modern 3.0 (quilt) source format, allowing maintainers to organize changes as an ordered stack of distinct diff files. This article explains how quilt operates inside a Debian source tree, how it manages modifications through its series file, and how it automates patch application during package builds.

The debian/patches Directory and the Series File

Debian encapsulates all modifications inside the debian/patches/ directory within the unpacked package source. The centerpiece of this system is the debian/patches/series file.

The series file acts as an index that defines the exact order in which patches must be applied to the upstream code. Each line contains the filename of a unified diff relative to the debian/patches/ directory. Lines preceded by # are treated as comments, enabling maintainers to temporarily disable specific patches without deleting them.

The Patch Stack Mechanism

quilt operates on the concept of a stack. Patches are applied sequentially from bottom to top and removed from top to bottom. The tool tracks applied patches using internal state directories (commonly .pc/):

  • quilt push: Applies the next patch in the series file to the source tree. Maintainers can run quilt push -a to apply all patches in sequence.
  • quilt pop: Reverses and removes the topmost applied patch, restoring files to their prior state. Maintainers use quilt pop -a to completely clean the source tree back to the original upstream state.
  • quilt applied and quilt unapplied: Display which patches are currently active on the tree and which remain pending in the stack.

Creating and Updating Patches

When maintaining a Debian package, quilt prevents manual, error-prone diff generation through a specific workflow:

  1. Initialize a new patch: Running quilt new <patch-name>.patch registers a new layer on top of the stack and appends its name to debian/patches/series.
  2. Track target files: Before editing any upstream file, the packager runs quilt add <path/to/file>. This commands quilt to take a snapshot of the unmodified file in the .pc/ directory.
  3. Make modifications: The maintainer edits the source code files using their standard tools.
  4. Generate the diff: Running quilt refresh compares the current state of modified files against the snapshots stored in .pc/ and writes the resulting diff directly into debian/patches/<patch-name>.patch.

Integration with Debian Build Tools

The primary advantage of using quilt in Debian is its native integration with dpkg-source and the 3.0 (quilt) format. Maintainers rarely need to invoke quilt manually during automated package builds.

When a Debian source package is unpacked using dpkg-source -x, the tool automatically unpacks the pristine upstream archive (.orig.tar.gz) and applies all patches listed in debian/patches/series in order. Conversely, when building source packages using dpkg-buildpackage or dpkg-source -b, the build system verifies that all patches are applied cleanly and flags any uncommitted modifications in the working tree, ensuring that all Debian-specific changes remain tracked, modular, and reviewable.