.\" -*- mode: troff; coding: utf-8 -*-
.TH "" "5" ""
.SH NAME
.LP
alpm-db-files - File format for listing files, directories and backup metadata contained in an installed \fBalpm-package\fR.
.SH DESCRIPTION
.LP
The \fBalpm-db-files\fR format is a textual format that lists the directories and files contained in a single \fBalpm-package\fR.
In addition, it encodes the checksum for any file in a package that should be backed up in case it is changed on the target system (see the \fBbackup\fR keyword in \fBPKGBUILD\fR, \fBPKGINFO\fR and \fBSRCINFO\fR for the relevant functionality).
.PP
Such files are named \fBfiles\fR and are located in \fBalpm-db\fR structures.
They are created by package management software (e.g. \fBpacman\fR) from the contents of \fBalpm-package\fR files (for the \fBbackup\fR functionality with the help of \fBPKGINFO\fR).
Package management software uses them to list and query the paths of directories and files contained in a package file and to track the state of files that should be backed up in case they are changed on the target system.
.PP
It is important to not confuse \fBalpm-db-files\fR with \fBalpm-repo-files\fR, which uses the same file name (\fBfiles\fR) but is used in the context of an \fBalpm-repo-db\fR.
.SS
General Format
.LP
An \fBalpm-db-files\fR file is a UTF-8 encoded, newline-delimited file.
.PP
The file may be empty, or contain one or two section headers with one or more section entries each.
Empty lines are ignored.
Comments are not supported.
.SS
Sections
.LP
Each section header line contains the section name in all capital letters, surrounded by percent signs (e.g. \f(CR%FILES%\fR).
Section names serve as key for each section-specific value.
.PP
Each section allows for one or more \fIsection-specific values\fR, following the \fIsection header line\fR.
.PP
Note, that if a package tracks no files (e.g. \fBalpm-meta-package\fR), then none of the following sections are present, and the \fBalpm-db-files\fR file is empty.
.SS
%FILES%
.LP
Each value in this section represents either a single file or directory path.
The following formatting rules apply to the paths:
.IP "\(bu" 3
Directories are always listed with a trailing slash (\f(CR/\fR).
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
All paths are relative to the system root (i.e., \f(CR/usr/bin/foo\fR is represented as \f(CRusr/bin/foo\fR).
.SS
%BACKUP%
.LP
Each value in this section is represented by a single file path, a tab and the \fBMD-5\fR(1) hash digest of the file as found in the \fBalpm-package\fR that the \fBalpm-db-files\fR file describes (e.g. \f(CRetc/foo.conf d41d8cd98f00b204e9800998ecf8427e\fR.
.PP
All file paths must be relative to the system root (i.e., \f(CR/usr/bin/foo\fR is represented as \f(CRusr/bin/foo\fR)
.PP
This section can only be present, if the \f(CR%FILES%\fR section is also present and each file path is expected to also be present as a value in the \f(CR%FILES%\fR section.
.SH EXAMPLES
.LP
The following is an example of an \fBalpm-db-files\fR file for a package named \f(CRfoo\fR:
.LP
.EX
%FILES%
etc/
etc/foo.conf
usr/
usr/bin/
usr/bin/foo
usr/share/
usr/share/doc/
usr/share/doc/foo/
usr/share/doc/foo/README.md

%BACKUP%
etc/foo.conf d41d8cd98f00b204e9800998ecf8427e
.EE
.PP
The \f(CR%FILES%\fR section lists the files and directory paths that belong to the package, while the \f(CR%BACKUP%\fR section captures the \fBMD-5\fR hash digest of a configuration file as found in the package file.
.SH SEE ALSO
.LP
\fBPKGBUILD\fR(5), \fBPKGINFO\fR(5), \fBSRCINFO\fR(5), \fBalpm-repo-files\fR(5), \fBalpm-db\fR(7), \fBalpm-meta-package\fR(7), \fBalpm-package\fR(7), \fBalpm-package-name\fR(7), \fBalpm-repo-db\fR(7), \fBpacman\fR(8)
.SH NOTES
.IP "1." 3
MD-5
.IP
.UR https://en.wikipedia.org/wiki/MD5
.UE