How to Clean Debian Control Files with wrap-and-sort

The wrap-and-sort utility is a command-line tool provided by the devscripts package designed to automate the formatting, wrapping, and alphabetization of Debian packaging metadata. By standardizing files such as debian/control, debian/copyright, and package installation manifests, it eliminates stylistic inconsistencies, removes redundant entries, and produces clean, readable diffs in version control systems.

Core Functions of wrap-and-sort

wrap-and-sort cleans up Debian packaging trees by parsing configuration files and applying consistent formatting rules. Its primary operations include:

  • Wrapping Dependency Lists: Long, comma-separated lists of dependencies (such as Build-Depends, Depends, and Recommends) are broken down across multiple lines. This prevents excessively long single lines that are difficult to read and review.
  • Alphabetical Sorting: The tool sorts dependency lists and package lists alphabetically. This helps maintainers quickly locate specific packages, spot missing libraries, and eliminate inadvertent duplicates.
  • Trailing Commas: When wrapping dependencies across separate lines, wrap-and-sort appends trailing commas. This formatting ensures that adding or removing an item in the future modifies only that specific line, keeping git diff outputs minimal and isolated.
  • Whitespace Normalization: Redundant whitespace, irregular indentations, and trailing spaces across fields are stripped and standardized according to the Debian Policy Manual conventions.

Supported Files and Metadata

wrap-and-sort targets multiple files inside the debian/ directory:

  • debian/control: Formats relationship fields (Depends, Build-Depends, Suggests, etc.) and can sort binary package blocks.
  • debian/copyright: Formats machine-readable copyright specifications (DEP-5), standardizing paragraphs and file patterns.
  • Helper Files (debian/*.install, debian/*.docs, etc.): Sorts file paths within Debhelper configuration files alphabetically, reducing merge conflicts and highlighting duplicate entries.

Key Command Options

Running wrap-and-sort without arguments performs safe, non-destructive formatting. However, package maintainers frequently use several specific flags to achieve the standard Debian layout:

  • -a (--wrap-always): Wraps all dependency lists onto individual lines, even if the list is short enough to fit on a single line. This enforces a one-package-per-line structure across the entire file.
  • -s (--short-indent): Indents wrapped lines to a standard format rather than aligning them with the field header, improving readability for deeply nested dependencies.
  • -b (--sort-binary-packages): Sorts the binary package stanzas in debian/control alphabetically by package name (while preserving the Source stanza at the top).
  • -k (--keep-first): Keeps the first dependency on the same line as the field name when wrapping.
  • -n (--no-cleanup): Prevents the removal of empty helper files or dead metadata entries.

Impact on Version Control and Collaboration

Before wrap-and-sort, adding a single build dependency often meant appending to a continuous line, which caused merge conflicts and obscured the actual change within version control histories.

By restructuring package lists into sorted, single-item lines with trailing commas, each package dependency occupies an independent line in the Git history. When a dependency is introduced, modified, or removed, the resulting patch cleanly reflects only that specific change, making peer reviews and automated packaging pipelines significantly more efficient across the Debian ecosystem.