The file named 'watch' in the debian directory is used to check for newer versions of upstream software is available and to download it if necessary. The download itself will be performed with the uscan(1) program from the ?devscripts package. It takes the path to the debian directory that uses the watch file as an argument or searches the dirtories underneath the current working directory.

Basically a watch file will have this format:


To allow the version to remain unspecified, it is expressed as a wildcard using regular expression in Perl format:


The uscan program will then execute a "dir" command and check all the files in that directory for the highest version number.

uscan also supports ftp protocol. Unfortunately, when working with http, HTML pages do not always contain directory listing with files. The complete (or relative) path of the .tar.gz file to be downloaded will appear as a hyperlink within the web page. We hence need two types of information, the path to the page announcing the file and a regular expression to grep for the right link:

  version=3 link_from_href-1.0.tar.gz

"" is the site from where you are downloading the source and "link_from_href.1.0.tar.gz" is obtained from the HTML source code (from the "<a href=" tags).

If HTML code has "<a href=foo/program-1.0.tar.gz>" inside it, for example, you will use foo/program-(.+)\.tar\.gz

Watch files with errors are generally wrong on this second part.

Generally you want a slightly more flexible regex for the tarball name so that if upstream switches tarball naming schemes or compression formats you are covered: foo/program-(.+)\.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz)))

For FTP sites it changes a little, but it's basically the same thing (man uscan will help you more then me on this).

But the nice part is to test it:

  uscan --report-status

If it's not working as expected, you can use debug to see what it's fetching and what it's (not) matching:

  uscan --report-status --debug

Redirector URLs

Files hosted on various big project hosting sites can be specified with a special "redirector" URL (see more details in 'man uscan'). This allows the upstream URLs to change without the need to adapt watch files of affected packages.


  # 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.\.(?:zip|tgz|tbz2|txz|tar\.gz|tar\.bz2|tar\.xz)

See also:


/!\ The github redirector is no longer needed since the github tags package can simply be used instead:<user>/<project>/tags .*/tarball/(\d[\d\.]+)

There should be no need to use it, but you can also use the redirector:

  # is a redirector for GitHub projects
  # It can be used as following:<user>/<project> (.+)\.(?:zip|tgz|tbz2|txz|tar\.gz|tar\.bz2|tar\.xz)

See also:

Google Code

/!\ The Google Code redirector is no longer needed since the Google Code download package can simply be used instead:<project>/downloads/list?can=1 .*/<project>-(\d[\d.]*)\.(?:zip|tgz|tbz2|txz|tar\.gz|tar\.bz2|tar\.xz)

There should be no need to use it, but you can also use the redirector:

  # Use /p/<project> to retrieve available downloads for <project>.
  # Append ?current to the resulting URL to retrieve only current downloads, not all.\d+.*)\.(?:zip|tgz|tbz2|txz|tar\.gz|tar\.bz2|tar\.xz)

See also: