ALPM-STATE-REPO(7)

📦 version 0.13.0, in arch rolling

💅 alpm-state-repo — a directory structure to track Arch Linux Package Management (ALPM) package repository state

okay so real talk bestie, this is a page from the Miscellaneous Information Manual, section 7 — the deep-lore corner of the man pages where all the ALPM concepts live. buckle up 🎀

✨ NAME ✨

state-repo — literally a directory structure to track Arch Linux Package Management (ALPM) package repository state. that's the whole vibe. 🦋

🌸 DESCRIPTION 🌸

So end users get their ALPM-based packages (peep alpm-package for the tea ☕) through package repositories (see alpm-repo). and those repos also carry database files describing their current state (see alpm-repo-db) so end users know what's up.

An alpm-state-repo is the maintainer-side glow-up 💅 — package repository maintainers use it to get a detailed view on several aspects of one or more package repositories:

  • The names of all alpm-package-bases and their respective versions currently provided in all tracked repositories.
  • A reference to the git tag, as well as the fully resolved git commit hash digest in an alpm-source-repo, that packages with the respective alpm-package-base are built from.

A state-repo is maintained using repository management software (e.g. dbscripts [1] — link at the bottom, iykyk). it's usually kept in a version controlled repository (e.g. git) so it can reflect on atomic changes to the contained data in dedicated commits. iconic behavior, no cap. ✨

🎀 FORMAT 🎀

An alpm-state-repo contains repository directories at its root, and each of those may contain zero or more state files.

🗂️ Repository directory

A repository directory represents architecture specific information about an alpm-repo. each directory name is an alpm-repo-name directly followed by a - sign, directly followed by an alpm-architecture. like, no space, no drama, just vibes. for example:

state
|-- core-any
|-- core-testing-x86_64
|-- core-x86_64
|-- extra-any
|-- extra-staging-any
|-- extra-staging-x86_64
|-- extra-testing-any
|-- extra-testing-x86_64
\-- extra-x86_64

Different from an alpm-repo, an alpm-state-repo distinguishes between architecture-dependent (e.g. x86_64) and architecture-independent (i.e. any) packages in a repository — and that's literally reflected in the directory naming. the combination of architecture-dependent and architecture-independent directories with the same alpm-repo-name comprise the state of an alpm-repo of the same name. for example: the directories core-any and core-x86_64 in an alpm-state-repo contain data for an alpm-repo named core. bestie they're a matching set 🫶

Each repository directory contains zero or more state files.

📄 State file

All files in a repository directory are named after an alpm-package-base for which they provide state data. each alpm-package-base implicitly refers to one or more alpm-packages in the respective alpm-repo that the repository directory targets.

A state file consists of a single line with the four components package name, version, tag and digest, each separated by a space:

  1. package name: the alpm-package-base of one or more alpm-packages in the targeted alpm-repo. ⚠️ this value must be identical to the name of the state file!
  2. version: the version of the alpm-package-base, formatted as an alpm-package-version in full or full with epoch variant.
  3. tag: the git tag in the alpm-source-repo from which all alpm-packages that share package name are built. this value is based on version but is subject to version normalization. (see below, it's giving transformation sequence 🧚)
  4. digest: the SHA-1 hash digest of the commit that tag points at in the alpm-source-repo.

🔄 Version normalization

Git literally cannot use certain characters in tags that are allowed in the alpm-package-version format 😭. so to be able to relate the version encoded in a PKGBUILD or SRCINFO file that is part of an alpm-source-repo — and by extension also the pkgver value found in a package's PKGINFO or BUILDINFO built from those sources — a tag undergoes normalization.

These modifications are applied in order to normalize the string:

  1. Replace all occurrences of : (colon) with a - (dash)
  2. Replace all occurrences of ~ (tilde) with a . (dot)

periodt. 💅

🔥 EXAMPLES 🔥

🍓 Single package

An alpm-package example in a repository named core is of architecture x86_64 and present in version 33-1. the package is the sole output from a package build process using an alpm-source-repo at the tag 33-1. the tag points at the commit with the SHA-1 hash digest 0685197a7fdc13a91e1b9184c2759a5bf222210f.

The file core-x86_64/example in the alpm-state-repo contains the following data:

example 33-1 33-1 0685197a7fdc13a91e1b9184c2759a5bf222210f

🌈 Single package with version normalization

The package example in a repository named extra-testing is of architecture x86_64 and present in version 17:4.3.2-10. the package is the sole output from a package build process using an alpm-source-repo at the tag 17-4.3.2-10. the tag points at the commit with the SHA-1 hash digest e4f06701c4ff5cda811a5663e83cf966a81f42e0.

The file extra-testing-x86_64/example in the alpm-state-repo contains the following data:

example 17:4.3.2-10 17-4.3.2-10 e4f06701c4ff5cda811a5663e83cf966a81f42e0

🦋 Split package

The alpm-packages example-a and example-b in a repository named core are of architecture x86_64 and are both present in version 1.0.0-1. the packages are both the output of a package build process using an alpm-source-repo at the tag 1.0.0-1. the tag points at the commit with the SHA-1 hash digest 0685197a7fdc13a91e1b9184c2759a5bf222210f. the PKGBUILD in the alpm-source-repo uses example-base as pkgbase.

The file core-x86_64/example-base in the alpm-state-repo contains the following data:

example-base 1.0.0-1 1.0.0-1 0685197a7fdc13a91e1b9184c2759a5bf222210f

👀 SEE ALSO 👀

the whole friend group came to support: git(1), PKGBUILD(5), alpm-architecture(7), alpm-package(7), alpm-package-base(7), alpm-package-name(7), alpm-package-version(7), alpm-repo(7), alpm-repo-db(7), alpm-repo-name(7), alpm-source-repo(7), alpm-split-package(7), devtools(7)

📌 NOTES 📌

  1. dbscripts

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

ok that's the whole page bestie, go forth and maintain those repos responsibly 🫶💖

and yeah — this came from the Miscellaneous Information Manual, section (7) (that's the footer, bestie, it's the man page version + section, mwah 💋).

📦 where this page comes from