Sort Debian package indexes safely with apt-sortpkgs

You will turn an unsorted Debian package or source index into sorted output without changing the input file. apt-sortpkgs writes everything to standard output, so you can inspect the result first and replace the original only after a successful check. 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. The manual page identifies the tool as part of APT 2.8.3, so examples describe this installed version. 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 ...]

Checkpoint: if the command is missing, stop here and install or repair the package through your normal package-management process. Do not copy a different binary into an APT directory just to satisfy this check.

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 according to 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 still untouched because shell redirection created a separate destination. Keep that distinction clear when working with a repository index: a successful command does not write 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 used 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.

Checkpoint: compare the first package names and representative fields in the new file with the input. For a larger file, count records before and after:

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

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

4. Use a configuration file when the choice is repeatable

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

$ 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 can be written with their short forms, -o and -c. Do not confuse an option that selects source ordering with an option that names the input file.

5. Replace an index only after checking the result

Shell redirection with > truncates an existing destination before apt-sortpkgs has finished. Treat replacement as a separate, potentially destructive step. 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 are satisfactory, preserve 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. The backup is your recovery path: restore it with cp --preserve=all /path/to/Packages.bak /path/to/Packages if the replacement is wrong. Do not delete the backup until a consumer has accepted the new index.

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)

Do not publish or install /tmp/sort.out after a non-zero status. Check the error, correct the path or permissions, and run the complete command again. This is also why writing to a separate destination is safer than redirecting directly over a live index.

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 have generated content elsewhere, write it to a controlled temporary file, confirm its permissions, and pass that file name to apt-sortpkgs. Keep temporary files away from shared directories when the index contains private repository details.