Add Upload Artefacts to debian/files with dpkg-distaddfile

Your extra tarball built fine, then vanished from the upload because nobody told dpkg about it: debian/files is where you fix that. It is the list of generated files that end up in the package's .changes file. The examples use dpkg-dev 1.22.6ubuntu6.6, whose installed deb-src-files(5) page describes three whitespace-delimited fields plus optional attributes.

Allow about 15 minutes. You need:

These commands change packaging metadata, not the installed system. If the package is valuable, work in a branch or make a version-control checkpoint first.

1. Know what the file is for

debian/files is an upload list. It records generated files that will be represented through the .changes file. It is not the manifest of files a binary package installs. A typical line has this shape:

filename section priority

For example:

sample.tar.gz misc optional

The filename is the artefact name. Section and priority mean the same as in Debian package control data, but the archive decides which values are acceptable. Do not guess a plausible-looking section or priority: use whatever the archive or package workflow receiving the upload requires.

Checkpoint: you are in the source package root and the control file exists.

$ pwd
$ test -f debian/control && printf '%s\n' 'source package root confirmed'
source package root confirmed

2. Add an artefact with dpkg-distaddfile

Use dpkg-distaddfile for an extra file rather than editing debian/files by hand. It takes three required arguments: filename, section and priority.

$ dpkg-distaddfile ../sample_1.0.orig.tar.gz misc optional

The filename is relative to the directory where dpkg-genchanges will look for the file. In the usual build layout that is the parent of the source tree, so ../sample_1.0.orig.tar.gz makes sense. The path is stored in the list. It is not a request to copy the artefact.

If the command succeeds, inspect the result straight away:

$ tail -n 1 debian/files
../sample_1.0.orig.tar.gz misc optional

The command can fail before changing the list if the source package metadata is incomplete. An isolated directory without debian/control is no substitute for a real source package. Fix the structure and rerun from its root.

3. Mark an automatically generated file

The only attribute deb-src-files(5) currently supports is automatic=yes. It is an optional, whitespace-delimited keyword-value field:

$ dpkg-distaddfile ../sample_1.0-1_amd64.deb misc optional
$ printf '%s\n' 'generated-report.txt misc optional automatic=yes' >> debian/files

The first line uses the supported helper. The second shows the resulting format, but direct editing is not your normal workflow: the man page says to use dpkg-gencontrol or dpkg-distaddfile to add entries. When you need the automatic attribute, use a generator or packaging helper that emits the complete line, then review its output.

Warning: do not invent attributes such as generated=true or source=yes. The installed version does not document them, and later tooling may reject or misread the entry.

4. Let dpkg-gencontrol add its binary entry

When dpkg-gencontrol generates binary package control data, it also adds the presumed binary package filename to debian/files. That is why a normal package build can fill the file without a hand-maintained list.

Run it through the package's established build process, not as an experiment on a production checkout. After the relevant build step, review the list:

$ sed -n '1,120p' debian/files
sample_1.0-1_amd64.deb misc optional

Your filename, section and priority will depend on the package. A second entry is not automatically a duplicate: source archives, binary packages and other upload artefacts each get their own line. Check the final list against the files the eventual .changes generation step can actually find.

5. Use a separate list when the workflow needs one

Both dpkg-distaddfile and dpkg-gencontrol accept -f followed immediately by a list-file name. It replaces debian/files as the file they read or write:

$ dpkg-distaddfile -fbuild-upload.list ../sample_1.0-1_amd64.deb misc optional
$ cat build-upload.list
../sample_1.0-1_amd64.deb misc optional

Keep the alternate list inside the build workflow's documented workspace. It is not a second source of truth unless your build configuration deliberately makes it one. Writing to build-upload.list does not update debian/files.

6. Recover from a wrong entry

Warning: stop before generating or signing a .changes file if an entry names the wrong artefact, uses the wrong archive metadata or points outside the expected build layout. A bad list can give you an incomplete upload or a release tool that cannot find a file. Signing or uploading is irreversible for the remote archive, so review first.

Check the line format and the file's existence without changing state:

$ awk 'NF > 0 { print NF, $0 }' debian/files
$ test -f ../sample_1.0-1_amd64.deb && printf '%s\n' 'artefact exists'
artefact exists

Non-empty ordinary lines should have at least three fields. An attribute adds another field. Whitespace inside a filename is not a supported way to represent one, because the format is whitespace-delimited.

Done means