Debian Watch File and Upstream Monitoring Guide

The debian/watch file is a core configuration file used in Debian packaging to automate the tracking, downloading, and verification of new upstream software releases. This article explains the purpose of the debian/watch file, how it interacts with the uscan utility to monitor external sources such as web servers and Git repositories, and how to write and configure effective watch patterns for streamlined package maintenance.

What Is the debian/watch File?

In the Debian GNU/Linux operating system, software packages are typically built from source code provided by an "upstream" developer or project. The debian/watch file resides inside the debian/ directory of a Debian source package. Its primary role is to specify where and how the Debian packaging tools can locate new versions of the upstream project.

The file is parsed primarily by uscan, a tool provided by the devscripts package. Debian maintainers and automated infrastructure (such as the Debian Package Tracking System) rely on uscan to periodically check upstream distribution points for newer tarballs or Git tags.

Core Syntax and Format

A debian/watch file is a plain text file containing instructions and regular expressions. Modern packaging standards use version 4 syntax, which must be declared on the first line:

version=4

A standard watch line contains three key components:

  1. Options (optional): Directives modifying download behavior, signature verification, or compression formats, enclosed in square brackets [...].
  2. URL Base: The HTTP, HTTPS, or FTP directory, or Git repository URL to monitor.
  3. Matching Pattern: A regular expression specifying how to identify release files or tags and extract the version string.

Basic HTTP/FTP Pattern

For a project hosting tarballs on an HTTP server, a typical entry looks like:

version=4
https://example.com/downloads/ project-(.+)\.tar\.(?:gz|bz2|xz)

In this example:

  • https://example.com/downloads/ is the base URL scanned for links.
  • project-(.+)\.tar\.(?:gz|bz2|xz) is the regex matching the archive files.
  • The parenthesis (.+) captures the upstream version string, which uscan uses to compare against the version recorded in debian/changelog.

Monitoring Code Hosting Platforms

Modern watch files frequently target platforms like GitHub or GitLab. Special redirector services or specific API patterns are commonly used to ensure stable matching.

A standard GitHub tag monitoring entry:

version=4
opts="filenamemangle=s%(?:.*?)?(?:v|version)?(\d[\d.]*)\.tar\.gz%project-$1.tar.gz%" \
https://github.com/user/project/tags .*/(?:v|version)?(\d[\d.]*)\.tar\.gz

Here, filenamemangle rewrites the downloaded file's name to match Debian's naming convention (<package>_<version>.orig.tar.gz).

Cryptographic Signature Verification

The debian/watch file also automates security verification by checking upstream OpenPGP/GPG signatures. By adding the pgpsigurlmangle option, uscan automatically downloads an associated .asc or .sig file and verifies it against the maintainer's keyring stored in debian/upstream/signing-key.asc:

version=4
opts="pgpsigurlmangle=s%$%.asc%" \
https://example.com/releases/ project-(.+)\.tar\.gz

If the signature fails verification, uscan aborts the download process.

Executing and Automating Upstream Checks

Maintainers test and run the configuration locally using the uscan command:

  • uscan --verbose: Scans upstream and reports whether a newer version exists without downloading it.
  • uscan --download: Downloads the new upstream tarball and places it in the parent directory.
  • uscan --download --rename: Downloads the archive and automatically renames it to Debian's <package>_<version>.orig.tar.<ext> format.

Within the broader Debian infrastructure, automated services regularly run uscan against every package in the archive. When a new release is detected, it is flagged on the Debian Package Tracker, alerting maintainers that an update is available to be packaged and integrated into the distribution.