Provided by: devscripts_2.14.1ubuntu0.1_amd64 bug

NAME

       uscan - scan/watch upstream sources for new releases of software

SYNOPSIS

       uscan [options] [path-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 watch  file,  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 3; this line is compulsory!
       version=3

       # Line continuations are performed with \

       # This is 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 is the format for an FTP site with regex special characters in
       # the filename part
       ftp://ftp.worldforge.org/pub/worldforge/libs/Atlas-C++/transitional/Atlas-C\+\+-(.+)\.tar\.gz

       # This is the format for an FTP site with directory pattern matching
       ftp://ftp.nessus.org/pub/nessus/nessus-([\d\.]+)/src/nessus-core-([\d\.]+)\.tar\.gz

       # 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.  uscan starts by downloading the homepage,
       # obtained by removing the last component of the URL; in this case,
       # http://www.cpan.org/modules/by-module/Text/
       http://www.cpan.org/modules/by-module/Text/Text-CSV_XS-(.+)\.tar\.gz

       # This is a variant HTTP format which allows direct specification of
       # the homepage:
       # Homepage  Pattern  [Version  [Action]]
       http://www.dataway.ch/~lukasl/amph/amph.html \
         files/amphetamine-([\d\.]*).tar.bz2

       # This one shows that recursive directory scanning works, in either of
       # two forms, as long as the website can handle requests of the form
       # http://site/inter/mediate/dir/
       http://tmrc.mit.edu/mirror/twisted/Twisted/(\d\.\d)/ \
         Twisted-([\d\.]*)\.tar\.bz2
       http://tmrc.mit.edu/mirror/twisted/Twisted/(\d\.\d)/Twisted-([\d\.]*)\.tar\.bz2

       # For maximum flexibility with upstream tarball formats, use this:
       http://example.com/example-(\d[\d.]*)\.(?:zip|tgz|tbz2|txz|tar\.(?:gz|bz2|xz))

       # qa.debian.org runs a redirector which allows a simpler form of URL
       # for SourceForge based projects. The format below will automatically
       # be rewritten to use the redirector.
       http://sf.net/audacity/audacity-src-(.+)\.tar\.gz

       # For GitHub projects you can use the tags or releases page.  Since the archive
       # URLs use only the version as the name, it is recommended to use a
       # filenamemangle to adjust the name of the downloaded file:
       opts="filenamemangle=s/(?:.*)?v?(\d[\d\.]*)\.tar\.gz/<project>-$1.tar.gz/" \
         https://github.com/<user>/<project>/tags (?:.*/)?v?(\d[\d\.]*)\.tar\.gz

       # For Google Code projects you should use the downloads page like this:
       http://code.google.com/p/<project>/downloads/list?can=1 \
         .*/<project>-(\d[\d.]*)\.tar\.gz

       # This is the format for a site which has funny version numbers;
       # the parenthesised groups will be joined with dots to make a
       # sanitised version number
       http://www.site.com/pub/foobar/foobar_v(\d+)_(\d+)\.tar\.gz

       # This is another way of handling site with funny version numbers,
       # this time using mangling.  (Note that multiple groups will be
       # concatenated before mangling is performed, and that mangling will
       # only be performed on the basename version number, not any path
       # version numbers.)
       opts="uversionmangle=s/^/0.0./" \
         ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/development/Wine-(.+)\.tar\.gz

       # Similarly, the upstream part of the Debian version number can be
       # mangled:
       opts=dversionmangle=s/\.dfsg\.\d+$// \
         http://some.site.org/some/path/foobar-(.+)\.tar\.gz

       # The filename is found by taking the last component of the URL and
       # removing everything after any '?'.  If this would not make a usable
       # filename, use filenamemangle.  For example,
       # <A href="http://foo.bar.org/download/?path=&download=foo-0.1.1.tar.gz">
       # could be handled as:
       # opts=filenamemangle=s/.*=(.*)/$1/ \
       #     http://foo.bar.org/download/\?path=&download=foo-(.+)\.tar\.gz
       #
       # <A href="http://foo.bar.org/download/?path=&download_version=0.1.1">
       # could be handled as:
       # opts=filenamemangle=s/.*=(.*)/foo-$1\.tar\.gz/ \
       #    http://foo.bar.org/download/\?path=&download_version=(.+)

       # The option downloadurlmangle can be used to mangle the URL of the file
       # to download.  This can only be used with http:// URLs.  This may be
       # necessary if the link given on the web page needs to be transformed in
       # some way into one which will work automatically, for example:
       # opts=downloadurlmangle=s/prdownload/download/ \
       #   http://developer.berlios.de/project/showfiles.php?group_id=2051 \
       #   http://prdownload.berlios.de/softdevice/vdr-softdevice-(.+).tgz

       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=3'.  This allows  for  future
       extensions without having to change the name of the file.

       There are two possibilities for the syntax of an HTTP watch file 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 (links of the form <a href=...>) 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, as long as there are no parentheses (`(' and ')') in this part of
       the  URL:  if  it  does,  the  directory name will be matched in the same way as the final
       component of the URL as described below.  (Note that regex metacharacters such as `+'  are
       regarded  literally  unless  they  are in a path component containing parentheses; see the
       Atlas-C++ example above.  Also, the parentheses must match within each path component.)

       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 at least one 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 Perl regexp groups, demarcated  by  `(...)',  joining  them
       with  `.'  as  a  separator,  and using the result as the version number of the file.  The
       version number will then be mangled if required by  the  uversionmangle  option  described
       below.   Finally,  the  file  versions are then compared to find the one with the greatest
       version number, as determined by dpkg --compare-versions.  Note  that  if  you  need  Perl
       groups  which  are  not  to be used in the version number, either use `(?:...)' or use the
       uversionmangle option to clean up the mess!

       The current (upstream) version can be specified as the second parameter in the watch  file
       line.   If  this  is  debian  or absent, then the current Debian version (as determined by
       debian/changelog) is used to determine the current upstream version.  The current upstream
       version  may  also  be  specified  by  the  command-line  option --upstream-version, which
       specifies the upstream version number of the currently installed package (i.e., the Debian
       version  number without epoch and Debian revision).  The upstream version number will then
       be mangled using the dversionmangle option if one is specified, as  described  below.   If
       the newest version available is newer than the current version, then it is downloaded into
       the parent directory, unless the --report or --report-status option has been  used.   Once
       the   file   has   been   downloaded,   then   a   symlink   to  the  file  is  made  from
       <package>_<version>.orig.tar.{gz|bz2|lzma|xz} as described by the help for  the  --symlink
       option.

       Finally,  if  a third parameter (an action) is given in the watch file 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(1).   (Note  that  the calling syntax was slightly different when using
       watch file without a `version=...' line; there the command executed was `command  filename
       version'.)  If the command is uupdate, then the --no-symlink option is given to uupdate as
       a first option, since any requested symlinking will already be done by uscan.

       The alternative version of the watch file 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 you want to match just the basename of
       the href, you can use a pattern like ".*/name-(.+)\.tar\.gz" if you know that there  is  a
       full  URL, or better still: "(?:.*/)?name-(.+)\.tar\.gz" if there may or may not be.  Note
       the use of (?:...) to avoid making a backreference.)  If any of the hrefs in the  homepage
       which match the (anchored) pattern are relative URLs, 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 watch file line may be prefixed with `opts=options', where options is a  comma-separated
       list  of  options.   The  whole  options string may be enclosed in double quotes, which is
       necessary if options contains any spaces.  The recognised options are as follows:

       active and passive (or pasv)
              If used on an FTP line, these override the choice of whether to use  PASV  mode  or
              not, and force the use of the specified mode for this site.

       uversionmangle=rules
              This  is  used to mangle the upstream version number as matched by the ftp://... or
              http:// rules as follows.  First, the rules string is split into multiple rules  at
              every  `;'.   Then  the  upstream version number is mangled by applying rule to the
              version, in a similar way to executing the Perl command:
                  $version =~ rule;
              for each rule.  Thus, suitable rules might be `s/^/0./'  to  prepend  `0.'  to  the
              version  number  and  `s/_/./g'  to change underscores into periods.  Note that the
              rule string may not contain commas; this should not be a problem.

              rule may only use the 's', 'tr' and 'y' operations.   When  the  's'  operation  is
              used,  only  the  'g', 'i' and 'x' flags are available and rule may not contain any
              expressions which have the potential to execute code (i.e.  the  (?{})  and  (??{})
              constructs are not supported).

              If  the  's'  operation  is  used,  the  replacement  can contain backreferences to
              expressions within parenthesis in the matching regexp, like  `s/-alpha(\d*)/.a$1/'.
              These backreferences must use the `$1' syntax, as the `\1' syntax is not supported.

       dversionmangle=rules
              This is used to mangle the Debian version number of the currently installed package
              in the same way as the uversionmangle option.   Thus,  a  suitable  rule  might  be
              `s/\.dfsg\.\d+$//'  to remove a `.dfsg.1' suffix from the Debian version number, or
              to handle `.pre6' type version numbers.  Again, the rules string  may  not  contain
              commas; this should not be a problem.

       versionmangle=rules
              This   is  a  syntactic  shorthand  for  uversionmangle=rules,dversionmangle=rules,
              applying the same rules to both the upstream and Debian version numbers.

       filenamemangle=rules
              This is used to mangle the filename with which the downloaded file will  be  saved,
              and  is  parsed  in the same way as the uversionmangle option.  Examples of its use
              are given in the examples section above.

       downloadurlmangle=rules
              This is used to mangle the URL to be used for  the  download.   The  URL  is  first
              computed based on the homepage downloaded and the pattern matched, then the version
              number is determined from this URL.  Finally, any rules given by  this  option  are
              applied  before the actual download attempt is made. An example of its use is given
              in the examples section above.

       pgpsigurlmangle=rules
              If present, the supplied rules will be applied to the  downloaded  URL  (after  any
              downloadurlmangle  rules, if present) to craft a new URL that will be used to fetch
              the detached OpenPGP signature file for the upstream tarball.   Some  common  rules
              might be `s/$/.asc/' or `s/$/.pgp/' or `s/$/.gpg/'.  This signature must be made by
              a key found in the keyring debian/upstream/signing-key.pgp or the  armored  keyring
              debian/upstream/signing-key.asc.   If  it  is  not valid, or not made by one of the
              listed keys, uscan will report an error.

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.

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

       2      Always check the directory name.

       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 changelog.  The
       default value for the regex is: ´PACKAGE(-.+)?', thus matching  directory  names  such  as
       PACKAGE and PACKAGE-version.

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 available newer versions but do not download anything.

       --report-status
              Report on the status of all packages, even those which are up-to-date, but  do  not
              download anything.

       --download
              Report and download.  (This is the default behaviour.)

       --destdir
              Path  of directory to which to download.  If the specified path is not absolute, it
              will be relative to one of the current  directory  or,  if  directory  scanning  is
              enabled, the package's source directory.

       --force-download
              Download upstream even if up to date (will not overwrite local files, however)

       --pasv Force PASV mode for FTP connections.

       --no-pasv
              Do not use PASV mode for FTP connections.

       --timeout N
              Set timeout to N seconds (default 20 seconds).

       --symlink
              Make  orig.tar.gz  symlinks to any downloaded files if their extensions are .tar.gz
              or .tgz.  This is also handled for orig.tar.bz2 (for upstream .tar.bz2,  .tbz,  and
              .tbz2),  orig.tar.lzma  (for  upstream  .tar.lzma,  .tlz,  .tlzm,  and .tlzma), and
              orig.tar.xz (for upstream .tar.xz and .txz).  (This is the default behaviour.)

       --rename
              Instead of symlinking, rename the downloaded files  to  their  Debian  orig.tar.gz,
              orig.tar.bz2, orig.tar.lzma, or orig.tar.xz names as described above.

       --repack
              After  having downloaded an lzma tar, xz tar, bzip tar or zip archive, repack it to
              a gzip tar archive, which is still currently required  as  a  member  of  a  Debian
              source  package. Does nothing if the downloaded archive is not an lzma tar archive,
              xz tar archive, bzip tar archive or a zip archive (i.e. it doesn't  match  a  .tlz,
              .tlzm,  .tlzma, .tar.lzma, .txz, .tar.xz, .tbz, .tbz2, .tar.bz2 or .zip extension).
              The unzip package must be installed in order to repack .zip archives, the  xz-utils
              package must be installed to repack lzma or xz tar archives.

       --no-symlink
              Don't make these symlinks and don't rename the files.

       --dehs Use an XML format for output, as required by the DEHS system.

       --no-dehs
              Use the traditional uscan output format.  (This is the default behaviour.)

       --package package
              Specify   the   name   of   the   package   to  check  for  rather  than  examining
              debian/changelog;  this  requires  the  --upstream-version  (unless  a  version  is
              specified  in  the  watch  file)  and --watchfile options as well.  Furthermore, no
              directory scanning will be done and nothing will be  downloaded.   This  option  is
              probably most useful in conjunction with the DEHS system (and --dehs).

       --upstream-version upstream-version
              Specify  the  current  upstream  version  rather  than  examine  the  watch file or
              changelog to determine it.  This is ignored if a directory scan is being  performed
              and more than one watch file is found.

       --watchfile watchfile
              Specify  the  watchfile  rather  than perform a directory scan to determine it.  If
              this option is used without --package, then uscan must be called  from  within  the
              Debian  package  source  tree  (so  that  debian/changelog  can  be found simply by
              stepping up through the tree).

       --download-version version
              Specify the  version  which  the  upstream  release  must  match  in  order  to  be
              considered, rather than using the release with the highest version.

       --download-current-version
              Download the currently packaged version

       --verbose
              Give verbose output.

       --no-verbose
              Don't give verbose output.  (This is the default behaviour.)

       --no-exclusion
              Do  not  automatically  exclude  files  mentioned  in debian/copyright field Files-
              Excluded

       --debug
              Dump the downloaded web pages to stdout for debugging your watch file.

       --check-dirname-level N
              See the above section Directory name checking for an explanation of this option.

       --check-dirname-regex regex
              See the above section Directory name checking for an explanation of this option.

       --user-agent, --useragent
              Override the default user agent header.

       --no-conf, --noconf
              Do not read any configuration files.  This can only be used  as  the  first  option
              given on the command-line.

       --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) makes the choice
              (primarily based on the FTP_PASSIVE environment variable).

       USCAN_TIMEOUT
              If set to a number N, then set the timeout to N seconds.  This is equivalent to the
              --timeout option.

       USCAN_SYMLINK
              If this is 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 is set to yes  or  symlink,
              then the symlinks will be made.  If it is set to rename, then the files are renamed
              (equivalent to the --rename option).

       USCAN_DEHS_OUTPUT
              If this is set to yes, then DEHS-style output will be used.  This is equivalent  to
              the --dehs option.

       USCAN_VERBOSE
              If  this  is  set to yes, then verbose output will be given.  This is equivalent to
              the --verbose option.

       USCAN_USER_AGENT
              If set, the specified user agent string will be used in place of the default.  This
              is equivalent to the --user-agent option.

       USCAN_DESTDIR
              If  set, the downloaded files will be placed in this directory.  This is equivalent
              to the --destdir option.

       USCAN_REPACK
              If this is set to yes, then after having downloaded a bzip tar, lzma tar,  xz  tar,
              or  zip  archive,  uscan  will  repack it to a gzip tar.  This is equivalent to the
              --repack option.

       USCAN_EXCLUSION
              If  this  is  set  to  no,  files  mentioned  in  the   field   Files-Excluded   of
              debian/copyright  will be ignored and no exclusion of files will be tried.  This is
              equivalent to the --no-exclusion option.

EXIT STATUS

       The exit status gives some indication of whether a newer version was found or not; one  is
       advised  to  read the output to determine exactly what happened and whether there were any
       warnings to be noted.

       0      Either --help or --version was used, or for some watch file which was  examined,  a
              newer upstream version was located.

       1      No newer upstream versions were located for any of the watch files examined.

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.

       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.

       Version 2
              devscripts  version  2.6.90:  The  first  incarnation of the current style of watch
              files.

       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 behaviour, change the
              non-version-number groups to be (?:...) instead of a plain (...) group.

SEE ALSO

       dpkg(1), perlre(1), uupdate(1), devscripts.conf(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.