SYNOPSIS

watchupstream [ options ] [ packagename ... ]

DESCRIPTION

The program watchupstream is a command line tool that uses uscan and debian/watch files to see whether there are newer upstream releases for a selection of Debian packages. The output on standard output is human readable but also easy to parse by scripts. No need to have the Debian packages installed; any Debian package can be queried.

The program does some caching, so it should be OK to use watchupstream frequently in crontab for a reasonable number of packages. Hint: start with a low number of packages.

There are three ways for selecting packages to be queried. One, using the package selection options documented below, two, by enumerating package names on the command line separated by spaces, and three, by reading package names from standard input.

The package names can be read from standard input in three formats. Format A is simply a list of package names, one name per line. Format B is the output of a previous run of watchupstream. Format C is a list of watch files. In formats B and C only the package names are used, the rest is ignored.

The package names can be binary and/or source package names. The program watchupstream looks up the source package names for the given binary package names, and continues with only the resulting list of source package names.

Missing debian/watch files can be added and bad debian/watch files can be overridden without modifying the Debian package. Simply put your watch file named sourcepackagename.watch in the directory ~/.watchupstream/watchfiles and this watch file will be used instead of the debian/watch in the package.

OPTIONS

Options for selecting packages to be queried:

--packre=regularexpression

Use the given regular expression on binary and source package names to select packages to be queried.

--maintre=regularexpression

Use the given regular expression on the "Maintainer:" field to select packages to be queried.

--uploadre=regularexpression

Use the given regular expression on the "Uploaders:" field to select packages to be queried.

--maintuploadre=regularexpression

Use the given regular expression on the "Maintainer:" and "Uploaders:" fields to select packages to be queried.

--installed

Select all packages that are installed on the local system.

--all

Select all packages known in Debian.

Options related to caching of query results:

--nocache

Perform the queries without returning cached results.

--noextract

Perform the queries without trying to extract debian/watch files from .diff.gz files.

--cacheonly

Perform the queries with only returning cached results.

--forget

Don't perform any query and remove the cached results for the selected packages. This option also deletes the file ~/.watchupstream/watchfiles/packagename.watch for each selected package.

--input

Don't perform any query and accept lines read from standard input as valid results. The lines read from standard input must be in format B, see above.

Various other options:

--export

Export the watch files to ~/.watchupstream/watchfiles/packagename.watch for each of the selected packages, except for watch files that produce the result "unknown". This option implies the option --nocache.

--try=url

Try to create a watch file automatically using the given url. This option implies the options --nocache and --export.

--sid=dist

Some prefer "unstable" in their /etc/apt/sources.list while other prefer "sid". With this option, the user can specify his/her preference. Default "sid".

EXAMPLES

watchupstream --packre='xslt.*-perl$'

watchupstream --maintre=niebur

watchupstream < sponsoredpackages.txt

watchupstream qiv --try=http://spiegl.de/qiv/download/

watchupstream gtans

--try=http://sourceforge.net/projects/gtans/files/gtans/1.1/gtans-1.1.tar.gz/download

watchupstream acct --try=http://ftp.gnu.org/gnu/acct/acct-6.3.tar.gz

watchupstream gmp --try=ftp://ftp.gnu.org/gnu/gmp/

ls ~/.watchupstream/watchfiles/*.watch|watchupstream