Using uscan to strip files from upstream tarballs

     See also: Javascript/Repacking

The uscan command (part of the devscripts package) introduced a number of enhancements starting with version 2.14.2 that are helpful to deal with upstream tarballs you need to modify on account of needing to remove some of the files due to DFSG non-compliance1 or other more practical considerations.

Contents

  1. Using uscan to strip files from upstream tarballs
    1. Files-Excluded field in debian/copyright
    2. Specifying a compression method
    3. Not yet implemented (but potentially helpful)
    4. Notes

Files-Excluded field in debian/copyright

By using the field Files-Excluded: 

Files-Excluded: foo/bar.js

in the header stanza of debian/copyright, you can exclude files from an upstream tarball (see the uscan(1) man page). Though this feature remains undocumented in the machine-readable debian/copyright format specification2, its language leaves open the ability to use as-yet undefined fields and has not proved an impediment to adoption by packagers thus far.

The field accepts a whitespace-delimited list of patterns, parsed in the same manner as the Files field. For example: 

Files-Excluded: */Makefile.in aclocal.m4 config.h.in configure

The mk-origtargz tool (also from devscripts) can repack the original tarball even if no debian/watch file is present.

In order to retain the repacking suffix on the tarball the repacksuffix opts must be used in debian/watch (see uscan(1) § repacksuffix=).

Regarding Lintian

Lintian will emit a warning when files specified in the Files-Excluded field nevertheless still exist in the source tree at the time of packaging. The tag used is source-ships-excluded-file.

Specifying a compression method

You can specify a specific compression method by combining the compression option with repack (see uscan(1) § --repack), either on the command line as: 

uscan --repack --compression <xz|gzip|bzip2|lzma>

or in the debian/watch file as: 

   1 version=4
   2   opts="repack,compression=lzma,dversionmangle=auto,repacksuffix=+dfsg" \
   3   http://some.site.org/some/path/foobar-@ANY_VERSION@@ARCHIVE_EXT@

Not yet implemented (but potentially helpful)

When repacking, tar --exclude-vcs is used. Usually there is no point in having VCS metainformation in upstream tarballs. It should be debated in a separate thread whether this option should be used unconditionally, but the current implementation is that way. So, in the example above, the specification of .git is redundant because it will be left out anyway. The feature to exclude VCS information from upstream tarballs will be subject of a future bug report.

Notes

  1. See Policy:6.8.8.2. Repackaged upstream source for more information. (1)

  2. The bug debian-policy #685506 was created to track this proposed addition, and it remains open still thirteen years hence (as of 2025). (2)

CategoryPackaging