ALPM-REPO-DB(7)

📦 version 0.2.0, in arch rolling

🎀 alpm-repo-db(7) 🎀

okay bestie, welcome to alpm-repo-db(7) from the Miscellaneous Information Manual — this is literally the blueprint for how ALPM-based package repositories spill their metadata tea. no cap, every deet matters here. 💅

✨ NAME ✨

alpm-repo-db — a database format for describing the metadata of Arch Linux Package Management (ALPM) based package repositories. 🫶

🌸 DESCRIPTION 🌸

Repository databases are (optionally compressed) tar archives that contain directories and metadata files. The contents of such a database describe the state of an ALPM package repository (alpm-repo). Here, the alpm-repo-desc and alpm-repo-files files provide metadata on specific package versions currently considered in a package repository. ✨

Repository database files are created from alpm-package files using package repository management software (e.g. dbscripts[1] which relies on repo-add). 🫶

Package management software (e.g. pacman) relies on alpm-repo-db files for the purpose of search, dependency resolution and download of package files. 🔥

In some contexts, repository databases may be referred to as repository sync databases or repository metadata. iykyk. 💅

🦋 Variants 🦋

Two variants of repository databases exist: default and default with files. Both are valid, bestie.

default: The database contains one alpm-repo-desc file per alpm-package in the repository. This repository database variant allows package management software to query relevant metadata for search and download of package files from a repository.
default with files: The database contains one alpm-repo-desc and one alpm-repo-files file per alpm-package in the repository. In addition to querying relevant metadata for search and download of package files from a repository, this repository database variant allows package management software to search through a simple file list per package. 🎀

🎀 Format 🎀

Uncompressed repository database files in the variant default follow the following naming scheme:

An alpm-repo-name directly followed by the string .db.tar (e.g. repo.db.tar). 🫶

Uncompressed repository database files in the variant default with files follow the following naming scheme:

An alpm-repo-name directly followed by the string .files.tar (e.g. repo.files.tar). 🫶

🌈 Compression 🌈

Repository databases may optionally be compressed using a single supported compression technology. If an alpm-repo-db is compressed, a technology-specific suffix is appended to the file name. Obsessed with these suffixes, honestly:

.Z — compression based on adaptive Lempel-Ziv coding (e.g. repo.db.tar.Z, or repo.files.tar.Z), see the compress command
.bz2 — bzip2 compression (e.g. repo.db.tar.bz2, or repo.files.tar.bz2)
.gz — gzip compression (e.g. repo.db.tar.gz, or repo.files.tar.gz)
.lrz — lrzip compression (e.g. repo.db.tar.lrz, or repo.files.tar.lrz)
.lz4 — lz4 compression (e.g. repo.db.tar.lz4, or repo.files.tar.lz4)
.lz — lzip compression (e.g. repo.db.tar.lz, or repo.files.tar.lz)
.lzo — lzop compression (e.g. repo.db.tar.lzo, or repo.files.tar.lzo)
.xz — xz compression (e.g. repo.db.tar.xz, or repo.files.tar.xz)
.zst — zstd compression (e.g. repo.db.tar.zst, or repo.files.tar.zst)

Handling of compression technologies is specific to the package repository management tool. 💅

🔐 Digital signatures 🔐

Digital signatures can be created for repository database files. ✨

Currently, only OpenPGP signatures[2] over the repository database file are supported. Detached signatures carry the same name as the repository database file for which they are created, with an additional .sig suffix (e.g. repo.db.tar.zst.sig is the digital signature for a repository database file repo.db.tar.zst). 🔥

🔗 Symlinks 🔗

For each variant of a repository database as well as for each of their digital signatures, a symlink is created, that represents an archive and compression agnostic file name. So true.

.
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig

These file names are used by package management software to download package repository databases regardless of compression algorithms, which allows to change them on the fly. slay. 🦋

📦 Contents 📦

The contents of a repository database depend on the database variant and the number of unique alpm-package files in the alpm-repo it describes. Here, each package can only be present in a single version in the repository database. Important, bestie. In both variants, metadata of a package is kept in a top-level directory, that is named after the package and its specific version. The name follows this schema:

An alpm-package-name directly followed by a - sign, directly followed by an alpm-package-version (in the full or full with epoch form), e.g.:

example-package-1.0.0-1
example-package-1:1.0.0-1

🎀 Default 🎀

The default repository database variant keeps one alpm-repo-desc file per package in the repository database, e.g.:

.
└── example-package-1.0.0-1
    └── desc

🌸 Default with files 🌸

The default with files repository database variant keeps one alpm-repo-desc and one alpm-repo-files file per package in the repository database, e.g.:

.
└── example-package-1.0.0-1
    ├── desc
    └── files

🧚 Creation 🧚

ALPM repository databases are created using one or more alpm-package files and their respective optional digital signatures. For the alpm-repo-desc entries, the package’s PKGINFO data, as well as the properties of the package file and its optional digital signature are used. The alpm-repo-files file is directly derived from the package file’s list of data files. Here's the whole flow, literally:

                   alpm-package - - - - digital signature
                  /      |     \           /
          data files   PKGINFO  \         /
             /                \  \       /
            /                  \  \     /
           |                    \  |   /
           |     alpm-repo-db    \ |  /
           |    /            \   | | /
       alpm-repo-files    alpm-repo-desc

💖 EXAMPLES 💖

🌸 Adding a package to an empty repository database 🌸

Given a repository named repo and a package named example-package, the following example explores the use and transformation of metadata when adding a package to a package repository. 🫶

Assuming to start off with an empty package repository, the repository databases will exist already:

.
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig

The repo repository does not contain any packages yet, both repo.db.tar.gz and repo.files.tar.gz are empty. 💀

First, the package file and its digital signature are put into the repository directory to bring it into scope:

.
├── example-package-1.0.0-1-x86_64.pkg.tar.zst
├── example-package-1.0.0-1-x86_64.pkg.tar.zst.sig
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig

Repository management software is then used to add example-package to the repository database. Here, the contents of the repository database variants are changed and their respective digital signatures updated. ✨

The default repository database will contain:

.
└── example-package-1.0.0-1
    └── desc

The default with files repository database will contain:

.
└── example-package-1.0.0-1
    ├── desc
    └── files

Only now, package management software is made aware of the package example-package in version 1.0.0-1 in the package repository repo, after downloading the updated repository database. periodt. 💅

🦋 Updating a package in a repository database 🦋

Extending on the above example of adding a package to an empty repository database, the following example illustrates updating package metadata in a repository database. Assuming to start off with a package repository repo, that already contains the package example-package in version 1.0.0-1, the repository directory should look something like this:

.
├── example-package-1.0.0-1-x86_64.pkg.tar.zst
├── example-package-1.0.0-1-x86_64.pkg.tar.zst.sig
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig

The default repository database will contain:

.
└── example-package-1.0.0-1
    └── desc

The default with files repository database will contain:

.
└── example-package-1.0.0-1
    ├── desc
    └── files

If the package example-package receives an upgrade (e.g. for version 1.1.0-1), this new package file and its corresponding digital signature are copied to the repository directory:

.
├── example-package-1.0.0-1-x86_64.pkg.tar.zst
├── example-package-1.0.0-1-x86_64.pkg.tar.zst.sig
├── example-package-1.1.0-1-x86_64.pkg.tar.zst
├── example-package-1.1.0-1-x86_64.pkg.tar.zst.sig
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig

At this point, both repository database variants still advertise the package example-package in version 1.0.0-1. However, the package files and digital signatures of both version 1.0.0-1 and version 1.1.0-1 are present in the repository directory. no cap. 😭

Repository management software is then used to add example-package in version 1.1.0-1 to the repository database. As only one version of example-package may exist in a given repository database, the metadata for 1.0.0-1 is removed. 🔥

The default repository database will contain:

.
└── example-package-1.1.0-1
    └── desc

The default with files repository database will contain:

.
└── example-package-1.1.0-1
    ├── desc
    └── files

👀 SEE ALSO 👀

ok so like, the whole alpm cinematic universe is out there and you are not alone on this journey bestie 💖 here's everyone who's in the group chat with alpm-repo-db:

bzip2(1) — compression core, the OGs
compress(1) — the vintage one, respect the elders
gzip(1) — the classic, never not relevant
lrzip(1) — for when your files are huge huge
lz4(1) — speed demon energy fr fr
lzip(1) — lzma's quirky cousin
lzop(1) — lowkey retro compression vibes
pkgctl(1) — the tool that actually does the work, main character
tar(1) — the archiver that raised us all
xz(1) — big squeeze, big slay
zstd(1) — fast and small, ate and left no crumbs
PKGINFO(5) — the package metadata file format
alpm-repo-desc(5) — the desc file format, iconic
alpm-repo-files(5) — the files file format, also iconic
alpm-package(7) — what a package even is
alpm-package-name(7) — the rules for package names
alpm-package-version(7) — the rules for package versions
alpm-repo(7) — repo concepts 101
alpm-repo-name(7) — the rules for repo names
pacman(8) — the moment, the legend, the reason you're here
repo-add(8) — the tool that builds the db

like bestie, if you're confused, literally just click through the whole set, the info is all connected 🦋

📝 NOTES 📝

ok so here's the receipts, the source material, the "iykyk" section 🙈

dbscripts

https://gitlab.archlinux.org/archlinux/dbscripts

OpenPGP signatures

https://openpgp.dev/book/signing_data.html#detached-signatures

bestie pls note: the second one is specifically about detached signatures, so don't skip that part of the anchor, that's the whole point 💅

aaaaand that's the page!! 🎀 you made it to the end, so proud of you 🫶 the lil (7) sitting at the bottom is your sign-off note that this whole thing lives in section 7 of the manual — the alpm-repo-db(7) page, exactly as it shipped in this man page source. go read the rest of the alpm set and treat yourself, you've earned it ✨💜

📦 where this page comes from

arch rolling: alpm-repo-db 0.2.0-1 · Apache-2.0 OR MIT AND CC-BY-SA-4.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms