Add an Extra Upload File with dpkg-distaddfile

You will add one generated file to the upload list used for a Debian source package, with the section and priority that should appear in its .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. It normally needs no elevated privileges. Do not use sudo to hide a wrong working directory or 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 purpose 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 a path relative to the directory from which you happen to invoke this command. The manual specifically warns about this distinction. Replace every example value with a real filename; the command rejects paths that do not have a valid package filename.

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

Use 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 change 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 accepts the list-file name attached 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

This is useful when a packaging workflow deliberately keeps more than one upload list. It does not merge the custom list into debian/files. If you write -f upload.list, the separate word is treated as an argument and the command fails because it no longer has exactly three non-option arguments.

There is no privileged operation in this example. The destination must 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.

5. Check the result before building

Review the list as plain text and verify that the referenced file 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 reads data only. It does not prove that the archive is valid, signed or suitable for publication; 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

The backup gives you an undo path. To restore the list exactly, run cp --preserve=all debian/files.before-distaddfile debian/files after checking that the backup is the one you intend to restore. Remove the backup only after the package workflow has been checked; deleting it is irreversible.

Common failure messages

• 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 containing debian/control; do not create dummy metadata.
• 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.