ALPM-MTREEV1(5)

📦 version 0.4.0, in arch rolling

💖 ALPM-MTREE 💖

from the File Formats Manual, section 5 — welcome bestie, this is the whole vibe of the package directory hierarchy description format ✨

🌸 NAME 🌸

ALPM-MTREE — the package directory hierarchy description format, and it's lowkey the blueprint for how a package’s files are laid out, no cap 💅

🦋 DESCRIPTION 🦋

Okay so the mtree format is literally a textual format that describes the hierarchy and metadata of files inside a directory 🗂️✨

It’s a well-known format that can, for example, be used for installation instructions or to verify metadata of files and the hierarchy of a directory. It’s giving “receipts but for your filesystem” 🧾

The ALPM-MTREE format adheres to the official mtree specification. But — and this is the important part — .MTREE files used in the context of ALPM packages only use a subset of the official mtree format that makes sense in the scope of packaging. So it’s not the whole mtree menu, just the parts that actually matter for packaging 🎀

✨ Properties ✨

.MTREE files that’re generated by makepkg only contain the following properties:

  • type
  • uid
  • gid
  • mode
  • time
  • size
  • md5
  • sha256
  • link

.MTREE files are used in the scope of ALPM based packages and usually relate to files inside of those respective packages. Because of this, all paths provided in an ALPM-MTREE must be relative to the package root, with the exception of link destinations, which may also represent absolute paths. So no random absolute paths in your main entries, bestie — that’s not the vibe 🚫📁

🎀 Path Type Property 🎀

Unlike all available types in mtree, ALPM-MTREE only allows three file types:

  • dir — A directory
  • file — A file
  • link — A symbolic link
⚠️ Other file types must not be used, as they represent hardware specific, or ad hoc types, that should not be included in a package. So don’t try it, bestie — that’s a no from the packaging committee 💀

🧚 Required Fields by File Type 🧚

ALPM-MTREE requires specific values to be set for certain file types, which is something mtree doesn’t enforce by specification. So yeah, it’s stricter than the original — it ate and left no crumbs 💅

The dir path type requires the following properties to be set:

  • path
  • uid
  • gid
  • mode
  • time

The file path type requires the following properties to be set:

  • path
  • uid
  • gid
  • mode
  • size
  • md5digest
  • sha256digest
  • time

The link path type requires the following properties to be set:

  • path
  • uid
  • gid
  • mode
  • link
  • time

👑 Usage in Pacman 👑

In Pacman, ALPM-MTREE files are solely used to verify that installed files are identical to the original files without having to keep the original package around. So it’s literally the “receipt” that says “yep, this file is exactly what we shipped” 🧾✅

.MTREE files are implicitly generated and included when creating packages via makepkg. The gzip-compressed .MTREE file is located in the root of ALPM based packages. So it’s just there, doing its thing, no extra steps required 🫶

💜 Versioning 💜

The ALPM-MTREE format exists in multiple versions. The information in this document is for version 1, which is outdated. The ALPM-MTREE version 1 format has been introduced with the release of pacman 4.6.0 on 2012-04-30. So yeah, version 1 is giving “throwback”, but it’s still the one documented here — periodt 📅✨

🔥 EXAMPLES 🔥

#mtree
/set type=file uid=0 gid=0 mode=644
./.BUILDINFO time=1696727741.0 size=5574 md5digest=04a85103d4780101c710a297aae33837 sha256digest=708be566788a6a2712bcd40425d93761569ede07371781374edb1f22e2a3eb96
./.PKGINFO time=1696727741.0 size=830 md5digest=bde30355e5b95a86c59afbd149cc28da sha256digest=3aa17bec02b34c157e7c739c62e0e37a9d19f1459d404d7c6f2c14c6008127cd
set mode=755 type=dir
./usr time=1731613789.0
./usr/bin time=1731613789.0
./usr/bin/resolvconf time=1731613789.0 mode=777 type=link link=resolvectl

🌈 Generation 🌈

ALPM’s mtree files are generated by calling:

bsdtar \
  --format=mtree \
  --options='!all,use-set,type,uid,gid,mode,time,size,md5,sha256,link' \
  $folder

That’s the exact incantation, bestie — don’t change a single character or the vibe check fails 😤✨

🌟 Usages 🌟

In the context of ALPM and pacman, the mtree file’s main purpose is to provide a performant way of getting a package’s file metadata without having to extract and read the whole package. So it’s fast, it’s efficient, it’s iconic 🚀

This data is then used to verify installed files on the target system against the original files from the package. Take a look at pacman’s query check functionality for more detail. Iykyk 👀

💌 SEE ALSO 💌

Signed, sealed, delivered: section 5 of the File Formats Manual, no date in the footer but you already know the vibes. Stay slay, verify your files, and don’t use hardware-specific types in packages 💅🫶✨

📦 where this page comes from