.\" -*- mode: troff; coding: utf-8 -*-
.TH "" "5" ""
.SH NAME
.LP
\fBALPM-MTREE\fR - Package directory hierarchy description format.
.SH DESCRIPTION
.LP
The \fBmtree\fR format is a textual format that describes the hierarchy and metadata of files in a directory.
.PP
\fBmtree\fR is 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.
.PP
The \fBALPM-MTREE\fR format adheres to the official \fBmtree\fR specification.
However, \fB.MTREE\fR files used in the context of ALPM packages only use a subset of the official \fBmtree\fR format that makes sense in the scope of packaging.
.SS
Properties
.LP
\fB.MTREE\fR files that\(cqre generated by \f(CRmakepkg\fR only contain the following properties:
.IP "\(bu" 3
\f(CRtype\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRuid\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRgid\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRmode\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRtime\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRsize\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRmd5\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRsha256\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRlink\fR
.LP
\f(CR.MTREE\fR files are used in the scope of ALPM based packages and usually relate to files inside of those respective packages.
Due to this, all paths provided in an \fBALPM-MTREE\fR must be relative to the package root, with the exception of link destinations, which may also represent absolute paths.
.SS
Path Type Property
.LP
In contrast to all available types in \fBmtree\fR, \fBALPM-MTREE\fR only allows three file types:
.IP "\(bu" 3
\f(CRdir\fR A directory
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRfile\fR A file
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRlink\fR A symbolic link
.LP
Other file types must not be used, as they represent hardware specific, or ad hoc types, that should not be included in a package.
.SS
Required Fields by File Type
.LP
\fBALPM-MTREE\fR requires specific values to be set for certain file types, which is something \fBmtree\fR doesn\(cqt enforce by specification.
.PP
The \fBdir\fR path type requires the following properties to be set:
.IP "\(bu" 3
\f(CRpath\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRuid\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRgid\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRmode\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRtime\fR
.LP
The \fBfile\fR path type requires the following properties to be set:
.IP "\(bu" 3
\f(CRpath\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRuid\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRgid\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRmode\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRsize\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRmd5_digest\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRsha256_digest\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRtime\fR
.LP
The \fBlink\fR path type requires the following properties to be set:
.IP "\(bu" 3
\f(CRpath\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRuid\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRgid\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRmode\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRlink\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
\f(CRtime\fR
.SS
Usage in Pacman
.LP
In Pacman \fBALPM-MTREE\fR files are solely used to verify that installed files are identical to the original files without having to keep the original package around.
\fB.MTREE\fR files are implicitly generated and included when creating packages via \f(CRmakepkg\fR.
The gzip-compressed \fB.MTREE\fR file is located in the root of ALPM based packages
.SS
Versioning
.LP
The \fBALPM-MTREE\fR format exists in multiple versions.
The information in this document is for version 1, which is outdated. The \fBALPM-MTREE\fR version 1 format has been introduced with the release of pacman 4.6.0 on 2012-04-30.
.SH EXAMPLES
.LP
.EX
#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
.EE
.SS
Generation
.LP
ALPM\(cqs mtree files are generated by calling:
.LP
.EX
bsdtar \e
  --format=mtree \e
  --options='!all,use-set,type,uid,gid,mode,time,size,md5,sha256,link' \e
  $folder
.EE
.SH Usages
.LP
In the context of ALPM and \f(CRpacman\fR, the \f(CRmtree\fR file\(cqs main purpose is to provide a performant way of getting a package\(cqs file metadata without having to extract and read the whole package.
.PP
This data is then used to verify installed files on the target system against the original files from the package.
Take a look at \f(CRpacman\fR\(cqs query check functionality for more detail.
.SH SEE ALSO
.LP
\fBmtree\fR(5), \fBmakepkg\fR(8), \fBpacman\fR(8)