Manpages

Manpage of USCAN

USCAN

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

NAME

uscan - scan upstream sources for new releases of software  

SYNOPSIS

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

DESCRIPTION

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!
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 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.  

PER-SITE OPTIONS

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.  

EXAMPLE

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
debuild

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.  

OPTIONS

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

CONFIGURATION VARIABLES

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:
USCAN_DOWNLOAD
If this is set to no, then newer upstream files will not be downloaded; this is equivalent to the --report or --no-download options.
USCAN_PASV
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).
USCAN_SYMLINK
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.
USCAN_VERBOSE
If this is set to yes, then verbose output will be given. This is equivalent to the --verbose option.
 

SEE ALSO

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

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.


 

Index

NAME
SYNOPSIS
DESCRIPTION
FORMAT of debian/watch files
PER-SITE OPTIONS
EXAMPLE
OPTIONS
CONFIGURATION VARIABLES
SEE ALSO
AUTHOR

This document was created by man2html, using the manual pages.
Time: 09:51:32 GMT, July 15, 2020