After more digging I've figured it out.
TL;DR
Pin: release X=Y filters against fields of the Release file using shorthand notation. In the release file the version should be the version of the release. e.g.) for Debian bullseye you could have Pin: release v=11, or for Ubuntu Jammy you could have Pin: release v=22.04. Origin should the author or vendor name. e.g.) Pin: release o=LP-PPA-mozillateam.
Pin: version X filters against the package version. e.g.) Pin: version 1:91.
Pin: origin X filters against the hostname. e.g.) Pin: origin ppa.launchpad.net.
Release File
In the Determination of Package Version and Distribution Properties section of man apt_preferences we find this.
The locations listed in the sources.list(5) file should provide Packages and Release files to describe the packages available at that location.
So each location (which has an origin) has a release file for each release available. In that link, we see the release file is hosted at dists/$DIST/InRelease.
On my local machine we have
$ apt-cache policy
500 http://ppa.launchpad.net/mozillateam/ppa/ubuntu jammy/main amd64 Packages
release v=22.04,o=LP-PPA-mozillateam,a=jammy,n=jammy,l=Firefox ESR and Thunderbird stable builds,c=main,b=amd64
origin ppa.launchpad.net
Here, you can see my local machine is using the jammy release. So the relevant release file is located at dists/jammy/InRelease. This gives us this file here: http://ppa.launchpad.net/mozillateam/ppa/ubuntu/dists/jammy/InRelease.
That release file is created by the person hosting the repository and contains meta-information about the distribution. Some of the information is optional, and some is not. Some of the optional fields include:
- Origin
- Label
- Version
- Suite
- Codename
And some of the non-optional fields include:
This is what you filter against when you specify Pin: release X= in your preferences file. It is also described when you run apt-cache policy. In the example above, we have:
- Origin:
o=LP-PPA-mozillateam
- Label:
l=Firefox ESR
- Version:
v=22.04
- Suite:
a=jammy
- Codename:
n=jammy
- Components:
c=main
NB: I couldn't find anything in the man page in relation to the b= field in the output of the apt-cache policy command.
Origin
As well as the above information in the release file, the location also has an origin. This is also included in the output of the apt-cache policy command. As you can see for the example above, it is ppa.launchpad.net.
This is what you filter against when you include Pin: origin X in your preferences file.
In the The Effect of APT Preferences section of the man page, it has this useful sentence:
This should not be confused with the Origin of a distribution as specified in a Release file. What follows the "Origin:" tag in a Release file is not an Internet address but an author or vendor name, such as "Debian" or "Ximian".
Version
Back to the Determination of Package Version and Distribution Properties section of the man page.
As mentioned above, it states:
The locations listed in the sources.list(5) file should provide Packages and Release files to describe the packages available at that location.
So as well as this release file, we also have a packages file. The man page goes on to say:
Only two lines in each record [of the package file] are relevant for setting APT priorities:
the Package: line
gives the package name
the Version: line
gives the version number for the named package
This is different to what it says for the Version field of the Release file, for which it says
the Version: line
names the release version. For example, the packages in the tree might belong to Debian release version 11.
If we find one of these package files, we can see this. For the package above, for my architecture, it is here: http://ppa.launchpad.net/mozillateam/ppa/ubuntu/dists/jammy/main/binary-amd64/Packages.xz
Within that compressed archive, we have a Packages file which contains a list of all the packages available and their versions (and lots of other information). Here is part of one of the many packages available:
Package: thunderbird
Priority: optional
Section: mail
Installed-Size: 227239
Maintainer: Ubuntu Mozilla Team <[email protected]>
Architecture: amd64
Version: 1:91.5.1+build1-0ubuntu1
This version is what you fiter against when you include Pin: version X in your preferences file.
If you run apt-cache policy on a specific package, you can see the versions available for that package.
$ apt-cache policy thunderbird
thunderbird:
Installed: 1:78.14.0-1~deb11u1
Candidate: 1:78.14.0-1~deb11u1
Version table:
1:91.5.1+build1-0ubuntu1 500
500 http://ppa.launchpad.net/mozillateam/ppa/ubuntu jammy/main amd64 Packages
1:91.5.1-1+b2 10
10 http://ftp.us.debian.org/debian unstable/main amd64 Packages
1:91.5.0-2~deb11u1 500
500 http://security.debian.org/debian-security bullseye-security/main amd64 Packages
*** 1:78.14.0-1~deb11u1 900
900 http://deb.debian.org/debian bullseye/main amd64 Packages
100 /var/lib/dpkg/status
Confusion with Version
It appears that the version specified in the release file doesn't always appear to be correct. For example, for Google Chrome, we have this:
$ apt-cache policy
900 http://dl.google.com/linux/chrome/deb stable/main amd64 Packages
release v=1.0,o=Google LLC,a=stable,n=stable,l=Google,c=main,b=amd64
origin dl.google.com
I'm not sure what this version is supposed to represent, as it doesn't match the versions in the packages file:
$ grep "Package\|Version" /var/lib/apt/lists/dl.google.com_linux_chrome_deb_dists_stable_main_binary-amd64_Packages
Package: google-chrome-beta
Version: 99.0.4844.17-1
Package: google-chrome-stable
Version: 98.0.4758.80-1
Package: google-chrome-unstable
Version: 100.0.4867.0-1
