Sort Debian Package Indexes Safely with apt-sortpkgs

Two index files that should match but will not diff cleanly are a miserable way to spend an evening. apt-sortpkgs puts a Debian package or source index into a stable order, and because it writes only to standard output, your input file is never touched. Allow about ten minutes for a small index, longer for a large archive file.

This guide uses APT 2.8.3 from the installed apt-utils package, and the manual page identifies the tool as part of APT 2.8.3. The command is normally unprivileged when reading a file in your working directory. You need elevated privileges only if the destination or source file is protected, and there is usually no reason to run the sorter as root.

1. Check the installed command

Confirm which executable will run and record its version:

$ command -v apt-sortpkgs
/usr/bin/apt-sortpkgs
$ apt-sortpkgs --version
apt 2.8.3 (amd64)

The short help output also confirms the positional input shape:

$ apt-sortpkgs --help
Usage: apt-sortpkgs [options] file1 [file2 ...]

2. Sort a binary package index

By default, the program uses binary package information ordering. It sorts records by package name and sorts the fields within each record by its internal rules. This example sends the result to a new file:

$ apt-sortpkgs /path/to/Packages > /path/to/Packages.sorted
$ test -s /path/to/Packages.sorted && echo 'sorted output exists'
sorted output exists

For a concrete shape, an input containing zeta before alpha produces alpha first. A small sample on this machine gives:

Package: alpha
Architecture: all
Version: 2.0

Package: zeta
Architecture: all
Version: 1.0

The blank line separates records. The original Packages file is untouched because shell redirection created a separate destination. A successful command never writes back to its input.

3. Sort a source index with source field ordering

Source indexes use a different internal field order. Pass --source, or its short form -s, when the input describes source packages:

$ apt-sortpkgs --source /path/to/Sources > /path/to/Sources.sorted
$ sed -n '1,12p' /path/to/Sources.sorted
Package: alpha
Version: 2.0
Directory: pool/main/a/alpha
Files:
  def 20 alpha.deb

The option changes the ordering rules for source records. It does not convert a binary index into a source index, and it does not fetch, compress or publish an index. Use the format that matches the file you already have.

$ grep -c '^Package: ' /path/to/Sources
$ grep -c '^Package: ' /path/to/Sources.sorted

The two counts should agree for a valid input. A mismatch is a reason to stop and investigate, not to overwrite the original.

4. Set the mode in a configuration file

The source-order switch maps to the configuration item APT::SortPkgs::Source. When a script or maintenance task always handles source indexes, put that setting in a small, reviewable file:

$ printf '%s\n' 'APT::SortPkgs::Source "true";' > /tmp/apt-sortpkgs-source.conf
$ apt-sortpkgs --config-file /tmp/apt-sortpkgs-source.conf /path/to/Sources > /path/to/Sources.sorted

--config-file reads the default APT configuration and then the file you name. The environment variable APT_CONFIG is different: the manual documents it for settings that must be present before the default configuration files are parsed. Use the explicit option for an ordinary per-command override, and read apt.conf(5) before adding more complex settings.

For a one-off setting, --option is shorter:

$ apt-sortpkgs --option APT::SortPkgs::Source=true /path/to/Sources > /path/to/Sources.sorted

Both --option and --config-file have short forms, -o and -c. Do not confuse an option that selects source ordering with one that names the input file.

5. Replace an index only after checking the result

First create a temporary output beside the real file, then inspect it:

$ apt-sortpkgs /path/to/Packages > /path/to/Packages.new
$ test -s /path/to/Packages.new
$ head -n 8 /path/to/Packages.new
$ grep -c '^Package: ' /path/to/Packages.new

When the checks look right, keep a backup and move the new file into place:

$ cp --preserve=all /path/to/Packages /path/to/Packages.bak
$ mv /path/to/Packages.new /path/to/Packages

These commands may need sudo if the index belongs to a protected system directory. If the directory is writable by your account, keep the operation unprivileged.

6. Handle errors without mistaking partial output for success

The program returns zero on normal operation and decimal 100 on error. For example, a missing input can still leave sorted records from an earlier input on standard output before the error is reported:

$ apt-sortpkgs /path/to/Packages /path/to/missing-file > /tmp/sort.out 2> /tmp/sort.err
$ printf 'status=%s\n' "$?"
status=100
$ sed -n '1,3p' /tmp/sort.err
E: Could not open file /path/to/missing-file - open (2: No such file or directory)

Input must be a seekable file. A pipe is not a substitute for a normal file, even though many Unix filters accept standard input. If you generated content elsewhere, write it to a controlled temporary file, confirm its permissions, and pass that file name to apt-sortpkgs. Keep temporary files out of shared directories when the index contains private repository details.