USCAN(1)

📦
version 2.26.11ubuntu1 · 15 versions
, in ubuntu stonking

💖 USCAN(1) — the manual, but make it bestie 💖

okay so like. hi. welcome to uscan(1), the scan/watch upstream sources for new releases of software girlies. she scans, she watches, she serves. let's get into it 🦋

✨ NAME ✨

uscan — scan and/or watch upstream sources to find shiny new releases of software 🌈

✨ SYNOPSIS ✨

uscan [options] [path]

✨ DESCRIPTION ✨

so for basic usage? bestie, you literally just run uscan with no arguments at all, from the root of the Debianized source tree — yk, the place where you can see the debian/ directory. or from a directory that contains multiple source trees, that works too 💅

unless you pass --watchfile, uscan goes recursively looking for valid source trees, starting from the current directory. (the details live down in the "Directory name checking" section, iykyk.)

for every valid source tree it finds, here's the whole lil routine that goes down. it's giving main character energy honestly:

  • uscan reads the first entry in debian/changelog to figure out the source package name <spkg> and the last upstream version 📖
  • uscan processes the watch lines in debian/watch, top to bottom, in one single pass 🏃‍♀️
    • uscan downloads a web page from the URL specified in debian/watch 🌐
    • uscan extracts the hrefs pointing at the upstream tarball(s) from that web page, using the matching-pattern specified in debian/watch 🔍
    • uscan downloads the upstream tarball with the highest version that's newer than the last upstream version ⬆️
    • uscan saves the downloaded tarball to the parent ../ directory: ../<upkg>-<uversion>.tar.gz 💾
    • uscan invokes mk-origtargz to create the source tarball: ../<spkg>_<oversion>.orig.tar.gz 🎀
      • for a multiple upstream tarball (MUT) package, the secondary upstream tarball gets named ../<spkg>_<oversion>.orig-<component>.tar.gz instead 🫶
    • repeat until literally all lines in debian/watch are processed 🔁
  • if you requested it, uscan invokes an update script. this could be uupdate, to create the Debianized source tree ../<spkg>-<oversion>/*, or it could be a custom script of your own 💫

now pls note the following, bestie, this part matters:

  • for simplicity, the compression method used in the examples is gzip with the .gz suffix. other methods like xz, bzip2 and lzma, with the corresponding xz, bz2 and lzma suffixes, are also totally allowed 🎁
  • since version 4 of debian/watch, uscan enables handling of multiple upstream tarball (MUT) packages, but honestly that's a rare case for Debian packaging. for a single upstream tarball package there's only one watch line and no ../<spkg>_<oversion>.orig-<component>.tar.gz at all 🙈
  • uscan with the --verbose option produces a human readable report of uscan's execution 📝
  • uscan with the --debug option produces a human readable report of uscan's execution, including internal variable states 🔬
  • uscan with the --extra-debug option produces a human readable report of uscan's execution, including internal variable states and the remote content during the "search" step 🕵️‍♀️
  • uscan with the --dehs option produces an upstream package status report in XML format, for other programs like the Debian External Health System 📊
  • the primary objective of uscan is to help you figure out whether the latest upstream tarball version is being used or not, and to download the latest upstream tarball. the ordering of versions is decided by dpkg --compare-versions 👑
  • uscan with the --safe option limits uscan's functionality to just its primary objective. both the repacking of downloaded files and the updating of the source tree get skipped, to avoid running unsafe scripts. it also changes the default to --no-download and --skip-signature 🛡️

✨ FORMAT OF THE WATCH FILE ✨

the current debian/watch format is described in the debian-watch(5) manpage. the old formats (version 1 to 4) are described in the debian-watch-4(5) manpage 📚

to convert a version <= 4 file into the last version, simply use:

uscan --update-watchfile

and then check the result, bestie. don't skip that step 💅

here's an example for the debian/copyright file which initiates automatic repackaging of the upstream tarball into <spkg>_<oversion>.orig.tar.gz. (in debian/copyright, the Files-Excluded and Files-Excluded-component stanzas are a part of the first paragraph, and there's a blank line before the following paragraphs which contain Files and other stanzas 🫶)

Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Files-Excluded: exclude-this
 exclude-dir
 */exclude-dir
 .*
 */js/jquery.js

Files: *
Copyright: ...
...

and here's another example for the debian/copyright file which initiates automatic repackaging of the multiple upstream tarballs into <spkg>_<oversion>.orig.tar.gz and <spkg>_<oversion>.orig-bar.tar.gz:

Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Files-Excluded: exclude-this
 exclude-dir
 */exclude-dir
 .*
 */js/jquery.js
Files-Excluded-bar: exclude-this
 exclude-dir
 */exclude-dir
 .*
 */js/jquery.js

Files: *
Copyright: ...
...

the debian/copyright file may also contain Files-Included and Files-Included-component stanzas, which include files that were previously excluded. this is useful when you wanna exclude most but not all files in a directory (a classic move) 💫

Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Files-Excluded: vendor-dir
Files-Included:
 vendor-dir/directory/to/keep
 vendor-dir/*/file-to-keep

Files: *
Copyright: ...
...

see mk-origtargz(1) for more 👀

✨ KEYRING FILE EXAMPLES ✨

ok so let's just assume the upstream "uscan test key (no secret) <none@debian.org>" signs its package with a secret OpenPGP key and publishes the corresponding public OpenPGP key 🔑 this public OpenPGP key can be identified in 3 ways using the hexadecimal form:

  • the fingerprint, as the 20 byte data calculated from the public OpenPGP key. E. g., 'CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254 3FAF'
  • the long keyid, as the last 8 byte data of the fingerprint. E. g., 'C77E2D6872543FAF'
  • the short keyid, which is the last 4 byte data of the fingerprint. E. g., '72543FAF'

considering the existence of the collision attack on the short keyid, the use of the long keyid is recommended for receiving keys from the public key servers. and you must verify the downloaded OpenPGP key using its full fingerprint value, which you know is the trusted one. no shortcuts, bestie 🙅‍♀️

the armored keyring file debian/upstream/signing-key.asc can be created by using the gpg command as follows:

$ gpg --recv-keys "C77E2D6872543FAF"
...
$ gpg --finger "C77E2D6872543FAF"
pub   4096R/72543FAF 2015-09-02
      Key fingerprint = CF21 8F0E 7EAB F584 B7E2  0402 C77E 2D68 7254 3FAF
uid                  uscan test key (no secret) <none@debian.org>
sub   4096R/52C6ED39 2015-09-02
$ cd path/to/<upkg>-<uversion>
$ mkdir -p debian/upstream
$ gpg --export --export-options export-minimal --armor \
      'CF21 8F0E 7EAB F584 B7E2  0402 C77E 2D68 7254 3FAF' \
      >debian/upstream/signing-key.asc

the binary keyring files, debian/upstream/signing-key.pgp and debian/upstream-signing-key.pgp, are still supported but deprecated 💀

if a group of developers sign the package, you need to list the fingerprints of all of them in the argument for gpg --export ... so the keyring contains all of their OpenPGP keys 🧑‍🤝‍🧑

sometimes you may wonder who made a signature file. you can get the public keyid used to create the detached signature file foo-2.0.tar.gz.asc by running gpg as:

$ gpg -vv foo-2.0.tar.gz.asc
gpg: armor: BEGIN PGP SIGNATURE
gpg: armor header: Version: GnuPG v1
:signature packet: algo 1, keyid C77E2D6872543FAF
      version 4, created 1445177469, md5len 0, sigclass 0x00
      digest algo 2, begin of digest 7a c7
      hashed subpkt 2 len 4 (sig created 2015-10-18)
      subpkt 16 len 8 (issuer key ID C77E2D6872543FAF)
      data: [4091 bits]
gpg: assuming signed data in `foo-2.0.tar.gz'
gpg: Signature made Sun 18 Oct 2015 11:11:09 PM JST using RSA key ID 72543FAF
...

✨ to be continued bestie, don't go anywhere ✨

✨ COMMANDLINE OPTIONS ✨

Okay so bestie, here's the tea: for just your basic everyday usage, uscan doesn't need you to set any of these options. They're all vibes you can add, not homework you have to do. 🎀

  • --conffile, --conf-file — Adds to or fully replaces the default config files (/etc/devscripts.conf and ~/.devscripts). The catch: this can only be the very first option you give on the command line, no exceptions.

To replace them:

uscan --conf-file test.conf --verbose

To add to them, slap a + in front:

uscan --conf-file +test.conf --verbose

And listen — if one --conf-file has no "+", then the default config files just get straight-up ignored. 💀

  • --no-conf, --noconf — Don't read any config files at all. Same rule as above: this can only be the first option on the command line.
  • --no-verbose — Don't report verbose information. (This is the default, so it's the chill mode. 😌)
  • --verbose, -v — Report verbose information. Give me all the details, bestie.
  • --debug, -vv — Report verbose info plus some internal state values. We're going deeper. 👀
  • --extra-debug, -vvv — Report verbose info including the downloaded web pages as they're processed, straight to STDERR, for debugging. Maximum yap mode, no cap.
  • --dehs — Sends DEHS style output (XML-type) to STDOUT, while sending all other uscan output to STDERR.
  • --no-dehs — Uses only the traditional uscan output format. (Also the default. 🫶)
  • --download, -d — Download the new upstream release. (Default behavior!)
  • --force-download, -dd — Download the new upstream release even if you're already up-to-date. Heads up: this may not overwrite the local file.
  • --overwrite-download, -ddd — Download the new upstream release even if you're already up-to-date. And this one may overwrite the local file. 🔥
  • --no-download, --nodownload — Don't download anything, just report the info. Previously downloaded tarballs may still be used. Fun lil side effect: it changes the default to --skip-signature.
  • --signature — Download the signature. (Default!)
  • --no-signature — Don't download the signature, but do verify it if it's already been downloaded.
  • --skip-signature — Don't even bother — no downloading the signature, no verifying it. We're skipping the whole moment. 🙈
  • --safe, --report — Avoids running anything unsafe by skipping both the repacking of the downloaded package and the updating of the new source tree. This flips the default to --no-download and --skip-signature.
If your whole goal of running uscan is to gather upstream package status in a security-conscious environment, you really really need to use this option. Don't skip it, bestie. 🚨
  • --report-status — This is literally the same thing as setting --verbose --safe.
  • --download-version version — Specify the exact version that the upstream release has to match to even be considered, instead of just grabbing whichever release has the highest version. (It's a best effort feature, so, y'know. ✨)
  • --download-debversion version — Specify the Debian package version you want, and it'll download the corresponding upstream release version for you. The dversionmangle and uversionmangle rules are taken into account. (Also best effort!)
  • --download-current-version — Downloads the currently packaged version. (Best effort feature, as always. 💅)
  • --check-dirname-level N — Peep the section "Directory name checking" below for the full explanation of this one.
  • --check-dirname-regex regex — Same deal — see "Directory name checking" below. 👑
  • --destdir path — Okay so normally, uscan changes its internal current directory to the package's source directory — the place where debian/ lives. Then the destination directory for the downloaded tarball and other files gets set to the parent directory ../ relative to that internal current directory.

But you can override that default destination directory by setting the --destdir option to whatever path you want. Here's the nuance, and it matters: if the path is a relative path, the destination directory is figured out relative to uscan's internal current directory at execution time. If the path is an absolute path, the destination directory is set to path no matter what the internal current directory is.

This whole thing is true not just for a simple single-source-tree run, but also for an advanced scanning run where subdirectories hold multiple source trees. ✨

There's one exception though: when --watchfile and --package are used together. In that case, both the internal current directory of execution and the default destination directory get set to the current directory . — the one where uscan was started. And yes, you can still override that default with --destdir.

  • --package package — Specify the name of the package to check for instead of peeking at debian/changelog. Just know this requires --upstream-version (unless a version is specified in the watch file) and --watchfile too. Also: no directory scanning happens and nothing gets downloaded. This option automatically sets --no-download and --skip-signature for you, and it's probably most useful alongside the DEHS system (and --dehs).
  • --upstream-version upstream-version — Specify the current upstream version instead of digging through debian/watch or debian/changelog to figure it out. Quick heads up: this gets ignored if a directory scan is happening and more than one debian/watch file turns up.
  • --vcs-export-uncompressed — Disables compression of tarballs exported from a version control system (Git or Subversion). This eats up more space, but saves time if mk-origtargz has to repack the tarball to exclude files. Fair warning: it forces repacking of all exported tarballs.
  • --watchfile watchfile — Specify the watchfile directly instead of doing a directory scan to find it. If you use this without --package, then uscan has to be called from inside the Debian package source tree (so it can find debian/changelog just by stepping up through the tree).

One exception, again: when --watchfile and --package are used together, uscan can be called from anywhere, and the internal current directory of execution and the default destination directory get set to the current directory . where uscan was started.

See the --destdir explanation above for more. 🫶

  • --bare — Disables all the site-specific special case codes for URL redirections and page content alterations. No extra frills, just the raw thing.
  • --http-header — Adds the specified header into HTTP requests for a matching url. You can use this option more than once, and the values have to be in the form baseUrl@Name=value. Example:
uscan --http-header https://example.org@My-Token=qwertyuiop

Security — listen up, this one's important:

The given baseUrl must exactly match the base url before the /. Like so:

|        --http-header value         |           Good for          | Never used |
+------------------------------------+-----------------------------+------------+
| https://example.org.com@Hdr=Value  | https://example.org.com/... |            |
| https://example.org.com/@Hdr=Value |                             |     X      |
| https://e.com:1879@Hdr=Value       | https://e.com:1879/...      |            |
| https://e.com:1879/dir@Hdr=Value   | https://e.com:1879/dir/...  |            |
| https://e.com:1879/dir/@Hdr=Value  |                             |     X      |
It is strongly recommended that you do not use this feature to pass a secret token over an unciphered connection (http://). 💀 Like, please. 🙏

You can use the USCAN_HTTP_HEADER variable (inside ~/.devscripts) to hide a secret token away from scripts. Smart queen behavior. 👑

  • --no-exclusion — Don't automatically exclude files that are mentioned in the debian/copyright field Files-Excluded.
  • --no-symlink — Don't rename, don't repack, just leave that upstream tarball alone.
  • --timeout N — Set the timeout to N seconds (default is 20 seconds).
  • --user-agent, --useragent — Override the default user agent header.
  • --help — Gives you brief usage information. Your lil cheat sheet. 📝
  • --version — Displays version information.

uscan also accepts the following options and passes them straight on to mk-origtargz:

  • --symlink — Makes orig.tar.gz (with the appropriate extension) a symlink to the downloaded files. (This is the default behavior. ✨)
  • --copy — Instead of symlinking like above, copies the downloaded files.
  • --rename — Instead of symlinking like above, renames the downloaded files.
  • --repack — After downloading an lzma tar, xz tar, bzip tar, gz tar, lz tar, zip, jar, xpi, or zstd archive, repacks it to the specified compression (check out --compression).

Heads up on what you'll need installed: the unzip package is required to repack zip, jar, and xpi archives. The xz-utils package is required to repack lzma or xz tar archives. zstd is required to repack zstd archives. And an lzip decompressor like plzip or lzip is required to repack lz tar archives.

  • --compression [ gzip | bzip2 | lzma | xz ] — If your upstream sources are getting repacked (either because you passed --repack or because debian/copyright has the Files-Excluded field), you get to pick the compression method through this parameter. The default is gzip for normal tarballs, and xz for tarballs generated directly from the git repository.
  • --copyright-file copyright-file — Excludes files mentioned in Files-Excluded inside the given copyright-file. Super handy when you're running uscan outside of a source package directory. 🎀

🎀 DEVSCRIPT CONFIGURATION VARIABLES 🎀

okay so for basic usage? uscan literally does not need you to set any of these. you can just... not. it's fine. but if you want to customize, here's the tea 💅

The two config files /etc/devscripts.conf and ~/.devscripts get sourced by a shell, in that order, to set configuration variables. Command line options can override them. Environment variable settings? ignored for this purpose, bestie, don't even try it. And if the first command line option you give is --noconf, those files will not be read at all. The recognized variables rn are:

  • USCAN_DOWNLOAD — download, or just report? 👀
    • no: same as --no-download, so newer upstream files will not be downloaded.
    • yes: same as --download, newer upstream files will be downloaded. This is the default behavior, periodt.
    • also peep --force-download and --overwrite-download.
  • USCAN_SAFE — if this is yes, uscan avoids running unsafe scripts by skipping BOTH the repacking of the downloaded package AND the updating of the new source tree. that's the --safe options equivalent. this also sets the default to --no-download and --skip-signature. safety first, queen 🛡️
  • USCAN_TIMEOUT — if set to a number N, the timeout becomes N seconds. equivalent to the --timeout option.
  • USCAN_SYMLINK — if set to no, then a pkg_version.orig.tar.{gz|bz2|lzma|xz} symlink will not be made (equivalent to the --no-symlink option). if it's yes or symlink, the symlinks will be made. if it's rename, then the files are renamed (equivalent to the --rename option). three moods, pick one ✨
  • USCAN_DEHS_OUTPUT — if set to yes, DEHS-style output gets used. equivalent to the --dehs option.
  • USCAN_VERBOSE — if set to yes, verbose output is given. equivalent to the --verbose option.
  • USCAN_USER_AGENT — if set, the specified user agent string is used in place of the default. equivalent to the --user-agent option.
  • USCAN_DESTDIR — if set, downloaded files get placed in this directory. equivalent to the --destdir option.
  • USCAN_REPACK — if set to yes, then after downloading a bzip tar, lzma tar, xz tar, zip or zstd archive, uscan will repack it to the specified compression (see --compression). equivalent to the --repack option.
  • USCAN_EXCLUSION — if set to no, files mentioned in the field Files-Excluded of debian/copyright are ignored and no exclusion of files gets tried. equivalent to the --no-exclusion option.
  • USCAN_HTTP_HEADER — if set, the specified http header will be used if URL match. equivalent to --http-header option.
  • USCAN_VCS_EXPORT_UNCOMPRESSED — if set to yes, tarballs exported from a version control system will not be compressed. equivalent to the --vcs-export-uncompressed option.

✨ EXIT STATUS ✨

the exit status gives you some indication of whether a newer version was found or not. but lowkey, you're advised to actually read the output to determine exactly what happened and whether there were any warnings to be noted. the number is a hint, not the whole story, iykyk 🫶

  • 0 — either --help or --version was used, or for some watch file which was examined, a newer upstream version was located. slay 💅
  • 1 — no newer upstream versions were located for any of the watch files examined. 😭

🔥 ADVANCED FEATURES 🔥

uscan has SO many other enhanced features that we skipped above for simplicity's sake. let's check their highlights, bestie.

uscan can be executed with path as its argument to change the starting directory of search from the current directory to path.

if you are not sure what exactly is happening behind the scene, please enable the --verbose option. if that's not enough? enable the --debug option too, to see all the internal activities. no secrets, main character energy only 👑

see "COMMANDLINE OPTIONS" and "DEVSCRIPT CONFIGURATION VARIABLES" for other variations.

🧚 Custom script

After processing other stuff, uscan will run script if requested in debian/watch. Otherwise there will be no extra action. simple as that.

A typical script is uupdate for non-native packages, but a custom script may be used. For compatibility with other tools such as git-buildpackage, it may not be wise to create custom scripts with random behavior ⚠️. Custom scripts, if created, should behave as if uupdate. For possible use case, see <http://bugs.debian.org/748474> as an example.

For info on how to request this script, please see debian-watch(5) for recommended version 5 format, or debian-watch-4(5) for old version 4 format.

See "HISTORY AND UPGRADING" for how uscan invokes a custom script (or uupdate).

🌈 URL diversion

Some popular web sites changed their web page structure, causing maintenance problems to the watch file. rude, honestly. There are some redirection services created to ease maintenance of the watch file. Currently, uscan makes automatic diversion of URL requests to the following URLs to cope with this situation:

🦋 Directory name checking

Similarly to several other scripts in the devscripts package, uscan explores the requested directory trees looking for debian/changelog and debian/watch files. As a safeguard against stray files causing potential problems, and in order to promote efficiency, it will examine the name of the parent directory once it finds the debian/changelog file, and check that the directory name corresponds to the package name. It will only attempt to download newer versions of the package and then perform any requested action if the directory name matches the package name. Precisely how it does this is controlled by two configuration file variables DEVSCRIPTS_CHECK_DIRNAME_LEVEL and DEVSCRIPTS_CHECK_DIRNAME_REGEX, and their corresponding command-line options --check-dirname-level and --check-dirname-regex.

DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:

  • 0 — Never check the directory name. live free 🌸
  • 1 — Only check the directory name if we have had to change directory in our search for debian/changelog, that is, the directory containing debian/changelog is not the directory from which uscan was invoked. This is the default behavior.
  • 2 — Always check the directory name. no chill, all vigilance 👀

The directory name is checked by testing whether the current directory name (as determined by pwd(1)) matches the regex given by the configuration file option DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the command line option --check-dirname-regex regex. Here regex is a Perl regex (see perlre(3perl)), which will be anchored at the beginning and the end. If regex contains a /, then it must match the full directory path. If not, then it must match the full directory name. If regex contains the string package, this will be replaced by the source package name, as determined from the debian/changelog. The default value for the regex is: package(-.+)?, thus matching directory names such as package and package-version.

💜 HISTORY AND UPGRADING 💜

This section briefly describes the backwards-incompatible watch file features which have been added in each watch file version, and the first version of the devscripts package which understood them. lore drop time 📜

Pre-version 2

The watch file syntax was significantly different in those days. Don't use it. If you are upgrading from a pre-version 2 watch file, you are advised to read this manpage and to start from scratch. genuinely, throw it away bestie 🗑️

Version 2

devscripts version 2.6.90: The first incarnation of the current style of watch files. This version is also deprecated and will be rejected after the Debian 11 release. ⚠️

Version 3

devscripts version 2.8.12: Introduced the following: correct handling of regex special characters in the path part, directory/path pattern matching, version number in several parts, version number mangling. Later versions have also introduced URL mangling.

If you are upgrading from version 2, the key incompatibility is if you have multiple groups in the pattern part; whereas only the first one would be used in version 2, they will ALL be used in version 3. To avoid this behavior, change the non-version-number groups to be (?: ... ) instead of a plain ( ... ) group.

  • uscan invokes the custom script as "script --upstream-version version ../spkg_version.orig.tar.gz".
  • uscan invokes the standard uupdate as "uupdate --no-symlink --upstream-version version ../spkg_version.orig.tar.gz".

Version 4

devscripts version 2.15.10: The first incarnation of watch files supporting multiple upstream tarballs.

The syntax of the watch file is relaxed to allow more spaces for readability. breathe, it's fine 💆

If you have a custom script in place of uupdate, you may also encounter problems updating from Version 3.

  • uscan invokes the custom script as "script --upstream-version version".
  • uscan invokes the standard uupdate as "uupdate --find --upstream-version version".

Restriction for --dehs is lifted by redirecting other output to STDERR when it is activated.

🌸 SEE ALSO 🌸

dpkg(1), mk-origtargz(1), perlre(1), uupdate(1), devscripts.conf(5), debian-watch(5), debian-watch-4(5)

👑 AUTHOR 👑

The original version of uscan was written by Christoph Lameter <clameter@debian.org>. Significant improvements, changes and bugfixes were made by Julian Gilbey <jdg@debian.org>. HTTP support was added by Piotr Roszatycki <dexter@debian.org>. The program was rewritten in Perl by Julian Gilbey. Xavier Guimard converted it in object-oriented Perl using Moo.

and that's the whole page, bestie, you made it to the end 🫶✨ shoutout to Debian Utilities for this one — it's the 2026-09-21 drop of USCAN(1). go find some upstream versions, periodt 💅🎀

📦 where this page comes from