USCANSection: User Commands (1)
Updated: Debian Utilities
Return to Main Contents
NAMEuscan - scan upstream sources for new releases of software
SYNOPSISuscan [options] [paths-to-debian-source-packages]
DESCRIPTIONuscan 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! version=2 # Line continuations are performed with \ # This the format for an FTP site: # Full-site-with-pattern [Version [Action]] ftp://ftp.tex.ac.uk/tex-archive/web/c_cpp/cweb/cweb-(.*)\.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 http://www.cpan.org/modules/by-module/Text/Text-CSV_XS-(.*)\.tar\.gz # This is a variant HTTP format with more possibilities: # Homepage Pattern [Version [Action]] http://www.dataway.ch/~lukasl/amph/amph.html \ files/amphetamine-([\d\.]*).tar.bz2
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 http://host.name/ 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 filenameis 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.
PER-SITE OPTIONSA 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.
EXAMPLEThis 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 debuild
CONFIGURATION VARIABLESThe 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:
SEE ALSOdpkg(1), perlre(1) and uupdate(1).
AUTHORThe original version of uscan was written by Christoph Lameter <firstname.lastname@example.org>. Significant improvements, changes and bugfixes were made by Julian Gilbey <email@example.com>. HTTP support was added by Piotr Roszatycki <firstname.lastname@example.org>. The program was rewritten in Perl by Julian Gilbey.
This document was created by man2html, using the manual pages.
Time: 06:14:53 GMT, October 23, 2021