Manpages

USCAN

NAME

SYNOPSIS

DESCRIPTION

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

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

EXAMPLE

#!/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

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

AUTHOR

Index

NAME

SYNOPSIS

DESCRIPTION

FORMAT of debian/watch files

PER-SITE OPTIONS

EXAMPLE

OPTIONS

CONFIGURATION VARIABLES

SEE ALSO

AUTHOR