ALPM-MTREE(5)

📦 version 0.4.0, in arch rolling

💖 ALPM-MTREE 💖

Okay bestie, welcome to ALPM-MTREE — it’s a File Formats Manual page, section 5, and it’s literally all about the package directory hierarchy description format ✨

🎀 NAME 🎀

ALPM-MTREE — the package directory hierarchy description format 💅

🌸 DESCRIPTION 🌸

Okay so the mtree format is a textual format that describes the hierarchy and metadata of files in a directory. No cap.

mtree is a well-known format that can, for example, be used for installation instructions or to verify files’ metadata and the hierarchy of a directory. It’s giving organized 🧚

The ALPM-MTREE format adheres to the official mtree specification. However — and this is the lil plot twist — .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. Lowkey iconic.

🎀 Properties 🎀

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

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

Furthermore, as mtree files are used in the scope of Arch Linux packaging and always relate to files inside of Arch Linux packages. Due to this, all paths inside an ALPM-MTREE must be relative to the package, except link destinations, which may point outside of a package. Periodt 💅

🌈 Path Type Property 🌈

In contrast to all available types in mtree, ALPM-MTREE only allows three file types:

  • dir — a directory
  • file — a file
  • link — a symbolic link

The other types are forbidden, as they should not be included in package. We don’t do that here 🫶

🦋 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 spec. So yes, this is the strict bestie behavior.

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
  • 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. Imagine not hoarding the original package — slay. .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. Yep, exactly there 👑

⭐ Versioning ⭐

The ALPM-MTREE format exists in multiple versions. The information in this document is for version 2, which is the current version. It has been introduced with the release of pacman 6.1.0 on 2024-03-04. Mark the calendar, bestie.

🔥 Changes since the last version 🔥

The md5 field is no longer generated, effectively making this a breaking change. Big breaking-change energy — keep that in mind 💀

🌟 EXAMPLES 🌟

Here’s the example, literally verbatim, no edits:

#mtree
/set type=file uid=0 gid=0 mode=644
./.BUILDINFO time=1696727741.0 size=5574 sha256digest=708be566788a6a2712bcd40425d93761569ede07371781374edb1f22e2a3eb96
./.PKGINFO time=1696727741.0 size=830 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,sha256,link' \
  $folder

👀 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 fast, so efficient ✨

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 🫶

mtree(5), makepkg(8), pacman(8) — go read those too, bestie 💖

From the File Formats Manual, section 5 — current format version 2, pacman 6.1.0 release date 2024-03-04. Mwah 💋

📦 where this page comes from