This page shall quickly gather Nelson's comments on the file 'watch' in the debian folder. It is used to download upstream's source or to check for the necessity of an update. The download itself will be performed with the uscan program of the ?devscripts package. It takes the path to the debian folder comprising the watch file as an argument or searches the dirs 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 as with Perl's regular expressions:
The uscan program will then execute a "dir" command and check all the files in that directory for the highest version number.
Sadly, different from ftp, which is also supported by uscan, http does not always allow to have the directory of files listed. The version will have to be read from a HTML page itself. 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 http://somesite.com/path link_from_href-1.0.tar.gz
"http://somesite.com/path" is the site from where you are downloading th esource and "link_from_href.1.0.tar.gz" is obtained from the HTML source code (from the "<a href=" tags).
If http://somesite.com/path HTML code has "<a href=foo/program-1.0.tar.gz>" inside it, for example, you will use
Watch files with errors are generally wrong on this second part.
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:
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
As a special case, files hosted on sourceforge can be specified with a special "sf redirector" URL (see more details in 'man uscan'). FYI, the code for this redirector is hosted at : http://svn.debian.org/viewsvn/qa/trunk/wml/watch/