Add an Extra Upload File with dpkg-distaddfile

Ship an extra tarball alongside your .deb and dpkg-distaddfile is what tells the upload metadata it exists. It adds one generated file to the upload list for a Debian source package, with the section and priority that should appear in the resulting .changes file. The command writes to debian/files by default, or to a list you name with -f. The examples match dpkg 1.22.6 from the installed dpkg-dev package.

Allow about ten minutes. You need a Debian package source tree with a readable debian/control and a file that follows the normal Debian package filename rules. This is a metadata change in the source tree, not a package build, and it normally needs no elevated privileges. Do not reach for sudo to paper over a wrong working directory or a file ownership problem.

1. Confirm the installed command

Run these read-only checks from any directory:

$ command -v dpkg-distaddfile
/usr/bin/dpkg-distaddfile
$ dpkg-distaddfile --version
Debian dpkg-distaddfile version 1.22.6.

The command takes exactly three non-option arguments: filename, section and priority. Its job is to add an entry, not to create or copy the file named by filename.

2. Start in the source package root

Change to the directory that contains debian/control. A typical layout has built files one directory above the source directory, because dpkg-genchanges commonly looks there for them:

$ cd /path/to/source-package
$ test -f debian/control && echo 'package metadata found'
package metadata found
$ ls -l ../demo_1.0-1_amd64.deb

Use the path that dpkg-genchanges will expect, not necessarily the path relative to wherever you happen to be invoking this command from: the manual specifically warns about that distinction. Replace every example value with a real filename; the command rejects paths that are not valid package filenames.

If the metadata check fails, stop and fix the working directory. The command may report an error about debian/control; that is a location problem, not a reason to create an empty control file.

3. Add the file to debian/files

Pass the filename, archive section and priority as separate, quoted shell arguments. For a binary package built for an optional utility, for example:

$ dpkg-distaddfile '../demo_1.0-1_amd64.deb' utils optional
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ cat debian/files
../demo_1.0-1_amd64.deb utils optional

A successful run appends one line containing the three values separated by spaces. The section and priority are labels for the .changes file: they do not rename the archive and do not touch its Debian control metadata.

4. Use a separate list when debian/files is not the target

The -f option tells the command to read or write another file instead of debian/files. The installed syntax expects the list-file name attached directly to the option, so use -fupload.list:

$ dpkg-distaddfile -fupload.list '../demo_1.0-1.tar.gz' misc optional
$ cat upload.list
../demo_1.0-1.tar.gz misc optional

• Useful for a packaging workflow that deliberately keeps more than one upload list. It never merges the custom list back into debian/files.
• Write -f upload.list as two words and it fails. The separate word is treated as another argument, so the command no longer sees exactly three non-option arguments.
• Nothing here needs privileges. The destination just has to be writable by your user.

If a custom list already exists, inspect it before running the command: the tool adds an entry to the selected list, so repeated runs can leave duplicate lines behind.

5. Check the result before building

Review the list as plain text and verify the referenced file actually exists at the recorded path:

$ while read -r filename section priority; do
    printf '%s: section=%s priority=%s\n' "$filename" "$section" "$priority"
    test -f "$filename" || printf 'missing: %s\n' "$filename" >&2
done < debian/files
../demo_1.0-1_amd64.deb: section=utils priority=optional
$ test -f ../demo_1.0-1_amd64.deb && echo 'upload file is present'
upload file is present

For a custom list, replace debian/files with upload.list. This check only reads data: it does not prove the archive is valid, signed or fit for publication, and later Debian tooling still has to validate and include it.

6. Recover from a wrong entry

If you added the wrong line, make a backup, edit only the mistaken line, then inspect the result:

$ cp --preserve=all debian/files debian/files.before-distaddfile
$ sed -i '\|^../wrong_1.0-1_amd64.deb |d' debian/files
$ diff -u debian/files.before-distaddfile debian/files
--- debian/files.before-distaddfile
+++ debian/files
-../wrong_1.0-1_amd64.deb utils optional

Common traps

• need exactly a filename, section and priority: check that the option and its value are joined as -fupload.list, and that exactly three non-option arguments remain.
• cannot write debian/control: run from the source package root that contains a real debian/control; do not create dummy metadata to work around it.
• invalid filename: use a valid Debian package filename and the path expected by the later changes-file step. Check the path and spelling with ls -l.
• A duplicate line: inspect the list before adding entries, then remove only the accidental duplicate using the backed-up workflow above.