debian mentors/ tutorials/ Writing a Watch File
.........................

Writing a Watch File

A WatchFile allows you to find out easily if there are new ?UpstreamVersions of your packages available, A tool named uscan can be used to check this by running it in an unpacked SourcePackage that was a debian/watch file. The information will automatically be added to your ?QA page.

To actually do this is easy. It only involves one file to your package. We need something to test it though, and that is uscan from the devscripts package. If you don't already have it then install it.

  # aptitude install devscripts

Once that is done you might want to read over the uscan man page.

First enter the source directory of your package and spawn an editor to edit the debian/watch file. First enter the version of watch file you are creating, at the moment this is

  version=3

Then add the line that points to your tarballs, this is a sort of regular expression. For instance:

  http://point-at-infinity.org/ssss/ssss-(.*)\.tar\.gz

is what I use for one of my packages.

The uscan tool will then look on the given host in the given directory for any files that match the expression you give it. If any files match and have a version number greater that your current version of the package then you will be notified.

You can test your file by running 

  $ uscan --report-status

and you will be told whether ther are any new versions. The --report-status option tells uscan to give some output even if there are no new files, and to not download any new files.

It is also possible to include commands to be run if there is a new version in debian/watch. If you want to do this you can add them to the end of the line like 

  http://point-at-infinity.org/ssss/ssss-(.*)\.tar\.gz debian uupdate

(See the uscan man page for the reason for putting debian there).

This means that if you run uscan and there is a new version it will be downloaded and the ?uupdate program will be run. This will integrate your changes in to the new upstream version.

The other advantage to using a watch file is that your ?QA page will tell you if there is a new version available. See my page for how this looks (and to see if I have been keeping up with my packages).