Download a new upstream version

Download a new upstream release or checking if a newer upstream release exists is usually needed when:

  • Fixing a bug to rule out that a more recent version may have already fixed the bug.

  • (As a source package maintainer) to check for, download, and package a newer upstream release.

Most of the source packages contain a watch file in the debian directory. This is a configuration file for the uscan(1) utility, which allows you to automatically search HTTP or FTP sites or git(1) repositories for newly available updates of the upstream project.

Note

If the source package does not contain a debian/watch file, there may be an explanation and instructions in the debain/README.source or debian/README.debian file (if available) that tell you how to proceed.

Best practices

Download upstream file(s) manually only if there is no automatic download mechanism and you can’t find any download instructions.

Packages may get distributed to hundreds of thousands of users. Humans are the weakest link in this distribution chain because we may accidentally miss or skip a verification step, misspell a URL, copy the wrong URL or copy a URL only partially, etc.

When downloading upstream file(s) manually, make sure to verify cryptographic signatures (if available). The signing key of the upstream project should be stored in the source package as debian/upstream/signing-key.asc (if the upstream project has a signing key).

uscan(1) verifies downloads against this signing key automatically (if available).

Download new upstream version (if available)

Running uscan(1) from the root of the source tree checks if a newer upstream version exists and downloads it:

uscan

If uscan(1) cannot find a newer upstream version, it returns exit code 1 and prints nothing to the standard output.

uscan(1) reads the first entry in debian/changelog to determine the name and version of the source package.

Add the --verbose flag to see more information (e.g., which version uscan(1) found):

uscan --verbose

Check for new upstream version (no download)

To check if a new update is available without downloading anything, run the uscan(1) command with the --safe flag from the root of the source tree:

uscan --safe

Force the download

Use the --force-download flag to download an upstream release from the upstream project, even if the upstream release is up-to-date with the source package:

uscan --force-download

Download the source of older versions from the upstream project

To download the source of a specific version from the upstream project, use the --download-version flag.

Basic syntax:

uscan --download-version VERSION

For example:

uscan --download-version '1.0'

To download the source for the current version of the source package from the upstream project, use the --download-current-version flag instead, which parses the version to download from the first entry in the debian/changelog file:

uscan --download-current-version

Note

The --download-version and --download-current-version flags are both a best-effort features of uscan(1).

There are special cases where they do not work for technical reasons.

Further reading