Manpage of USCAN


Section: User Commands (1)
Updated: Debian Utilities
Return to Main Contents


uscan - scan upstream sources for new releases of software  


uscan [options] [paths-to-debian-source-packages]  


uscan scans the given directories (or the current directory if none are specified) and all of their subdirectories for packages containing a control file debian/watch. Parameters are then read from those control files and upstream ftp or http sites are inspected for newly available updates (as compared with the upstream version number retrieved from the debian/changelog file in the same directory). The newest updates are retrieved (as determined by their version numbers) and if specified in the watchfile, a program may then be executed on the newly downloaded source.

The traditional debian/watch files can still be used, but the current format offers both simpler and more flexible services. We do not describe the old format here; for their documentation, see the source code for uscan.


FORMAT of debian/watch files

The following demonstrates the type of entries which can appear in a debian/watch file. Obviously, not all of these would appear in one such file; usually, one would have one line for the current package.

# format version number, currently 2; this line is compulsory!

# Line continuations are performed with \

# This the format for an FTP site:
# Full-site-with-pattern  [Version  [Action]]*)\.tar\.gz \
  debian  uupdate

# This can be used if you want to override the PASV setting
# for a specific site
# opts=pasv ftp://.../...

# This is one format for an HTTP site, which is the same
# as the FTP format*)\.tar\.gz

# This is a variant HTTP format with more possibilities:
# Homepage  Pattern  [Version  [Action]] \

Comment lines may be introduced with a `#' character. Continuation lines may be indicated by terminating a line with a backslash character.

The first (non-comment) line of the file must begin `version=2'. This allows for future extensions without having to change the name of the file.

There are two possibilities for the syntax of an HTTP watchfile line, and only one for an FTP line. We begin with the common (and simpler) format. We describe the optional opts=... first field below, and ignore it in what follows.

The first field gives the full pattern of URLs being searched for. In the case of an FTP site, the directory listing for the requested directory will be requested and this will be scanned for files matching the basename (everything after the trailing `/'). In the case of an HTTP site, the URL obtained by stripping everything after the trailing slash will be downloaded and searched for hrefs to either the full URL pattern given, or to the absolute part (everything without the part), or to the basename (just the part after the final `/'). Everything up to the final slash is taken as a verbatim URL.

The pattern (after the final slash) is a Perl regexp (see perlre(1) for details of these). You need to make the pattern so tight that it matches only the upstream software you are interested in, and nothing else. Also, the pattern will be anchored at the beginning and at the end, so it must match the full filename. (Note that for HTTP URLs, the href may include the absolute path or full site and path and still be accepted.) The pattern must contain a Perl group as explained in the next paragraph.

Having got a list of `files' matching the pattern, their version numbers are extracted by treating the part matching the first Perl regexp group, demarcated by `(...)', as the version number of the file. The file versions are then compared to find the one with the greatest version number, as determined by dpkg --compare-versions.

The current version can be specified as the second parameter in the watchfile line. If this is debian or absent, then the current version (as determined by debian/changelog) is used. If the newest version available is newer than the current version, then it is downloaded into the parent directory, unless the --report option has been used. Once the file has been downloaded, then a symlink to the file is made from <package>_<version>.orig.tar.gz if the file has a .tar.gz or a .tgz suffix.

Finally, if a third parameter is given in the watchfile line, this is taken as the name of a command, and the command

    command --upstream-version version filename
is executed, using either the original file or the symlink name. A common such command would be uupdate. (Note that the calling syntax was slightly different when using watchfiles without a `version=2' line; there the command executed was `command filename version'.)

The alternative version of the watchfile syntax for HTTP URLs is as follows. The first field is a homepage which should be downloaded and then searched for hrefs matching the pattern given in the second field. (Again, this pattern will be anchored at the beginning and the end, so it must match the whole href.) If any of these hrefs are relative, they will be taken as being relative to the base URL of the homepage (i.e., with everything after the trailing slash removed), or relative to the base URL specified in the homepage itself with a <base href="..."> tag. The third and fourth fields are the version number and action fields as before.  


A watchfile line may be prefixed with "opts=options", where options is a comma-separated list of options. The only recognised options are currently active and passive (or pasv), which if used on an FTP line override the choice of whether to use PASV mode or not, and force the use of the specified mode for this site.  


This script will perform a fully automatic upstream update.

#!/bin/sh -e
# called with '--upstream-version' <version> <file>
uupdate "$@"
package=`dpkg-parsechangelog | sed -n 's/^Source: //p'`
cd ../$package-$2

Note that we don't call dupload or dput automatically, as the maintainer should perform sanity checks on the software before uploading it to Debian.  


--report, --no-download
Only report about newer or absent versions but do not download anything.
Report and download. (This is the default behaviour.)
Force PASV mode for FTP connections.
Do not use PASV mode for FTP connections.
Make orig.tar.gz symlinks to any downloaded files if their extensions are .tar.gz or .tgz. (This is the default behaviour.)
Don't make these symlinks.
Give verbose output.
Don't give verbose output. (This is the default behaviour.)
Give brief usage information.
Display version information.


The two configuration files /etc/devscripts.conf and ~/.devscripts are sourced by a shell in that order to set configuration variables. These may be overridden by command line options. Environment variable settings are ignored for this purpose. If the first command line option given is --noconf, then these files will not be read. The currently recognised variables are:
If this is set to no, then newer upstream files will not be downloaded; this is equivalent to the --report or --no-download options.
If this is set to yes or no, this will force FTP connections to use PASV mode or not to, respectively. If this is set to default, then Net::FTP(3) make the choice (primarily based on the FTP_PASSIVE environment variable).
If this is set to no, then a pkg_version.orig.tar.gz symlink will not be made. This is equivalent to the --no-symlink option.
If this is set to yes, then verbose output will be given. This is equivalent to the --verbose option.


dpkg(1), perlre(1) and uupdate(1).  


The original version of uscan was written by Christoph Lameter <>. Significant improvements, changes and bugfixes were made by Julian Gilbey <>. HTTP support was added by Piotr Roszatycki <>. The program was rewritten in Perl by Julian Gilbey.



FORMAT of debian/watch files

This document was created by man2html, using the manual pages.
Time: 06:14:53 GMT, October 23, 2021