.TH "alpm-state-repo" 7

.SH "NAME"
.PP
state\-repo \- a directory structure to track \fBA\fPrch \fBL\fPinux \fBP\fPackage \fBM\fPanagement (ALPM) package repository state\.

.SH "DESCRIPTION"
.PP
End users gain access to ALPM based packages (see \fBalpm\-package\fP) through package repositories (see \fBalpm\-repo\fP)\.
These also contain database files describing their current state (see \fBalpm\-repo\-database\fP) to the end users\.
.PP
An \fBalpm\-state\-repo\fP is used by package repository maintainers and provides a detailed view on several aspects of one or more package repositories:
.RS
.Bl
.IP \(bu 4
The names of all \fBalpm\-package\-bases\fP and their respective versions currently provided in all tracked repositories\.
.El
.Bl
.IP \(bu 4
A reference to the git tag, as well as the fully resolved git commit hash digest in an \fBalpm\-source\-repo\fP, that packages with the respective \fBalpm\-package\-base\fP are built from\.
.El
.RE
.PP
A state\-repo is maintained using repository management software (e\.g\. \fBdbscripts\fP [1])\.
It is usually kept in a version controlled repository (e\.g\. \fBgit\fP) to reflect on atomic changes to the contained data in dedicated commits\.

.SH "FORMAT"
.PP
An \fBalpm\-state\-repo\fP contains \fBrepository directories\fP at its root which each may contain zero or more \fBstate files\fP\.

.SS "Repository directory"
.PP
A repository directory represents architecture specific information about an \fBalpm\-repo\fP\.
Each directory name consists of an \fBalpm\-repo\-name\fP directly followed by a '\-' sign, directly followed by an \fBalpm\-architecture\fP, e\.g\.:
.RS
.PP
.nf
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
.fi
.RE
.PP
Different from an \fBalpm\-repo\fP, an \fBalpm\-state\-repo\fP distinguishes between architecture\-dependent (e\.g\. `\f[CR]x86_64\fP`) and architecture\-independent (i\.e\. `\f[CR]any\fP`) packages in a repository, which is reflected in the directory naming\.
The combination of architecture\-dependent and architecture\-independent directories with the same \fBalpm\-repo\-name\fP comprise the state of an \fBalpm\-repo\fP of the same name (e\.g\. the directories `\f[CR]core\-any\fP` and `\f[CR]core\-x86_64\fP` in an \fBalpm\-state\-repo\fP contain data for an \fBalpm\-repo\fP named `\f[CR]core\fP`)\.
.PP
Each \fBrepository directory\fP contains zero or more \fBstate files\fP\.

.SS "State file"
.PP
All files in a \fBrepository directory\fP are named after an \fBalpm\-package\-base\fP for which they provide state data\.
Each \fBalpm\-package\-base\fP implicitly refers to one or more \fBalpm\-packages\fP in the respective \fBalpm\-repo\fP that the \fBrepository directory\fP targets\.
.PP
A state file consists of a single line with the four components \fIpackage name\fP, \fIversion\fP, \fItag\fP and \fIdigest\fP, each separated by a space:
.RS
.Bl
.IP 1. 4
\fIpackage name\fP: The \fBalpm\-package\-base\fP of one or more \fBalpm\-packages\fP in the targeted \fBalpm\-repo\fP\.
This value must be identical to the name of the \fBstate file\fP!
.El
.Bl
.IP 2. 4
\fIversion\fP: The version of the \fBalpm\-package\-base\fP, formatted as an \fBalpm\-package\-version\fP in \fBfull\fP or \fBfull with epoch\fP variant\.
.El
.Bl
.IP 3. 4
\fItag\fP: The git tag in the \fBalpm\-source\-repo\fP from which all \fBalpm\-packages\fP that share \fIpackage name\fP are built\.
This value is based on \fIversion\fP but is subject to \fBversion normalization\fP\.
.El
.Bl
.IP 4. 4
\fIdigest\fP: The SHA\-1 hash digest of the commit that \fItag\fP points at in the \fBalpm\-source\-repo\fP\.
.El
.RE

.SB "Version normalization"
.PP
Git is not able to use certain characters in tags that are allowed in the \fBalpm\-package\-version\fP format\.
To be able to relate the version encoded in a \fBPKGBUILD\fP or \fBSRCINFO\fP file that is part of an \fBalpm\-source\-repo\fP and by extension also the \fBpkgver\fP value found in a package's \fBPKGINFO\fP or \fBBUILDINFO\fP built from those sources, a tag undergoes normalization\.
.PP
The following modifications are applied in order to normalize the string:
.RS
.Bl
.IP 1. 4
Replace all occurrences of ':' (colon) with a '\-' (dash)
.El
.Bl
.IP 2. 4
Replace all occurrences of '~' (tilde) with a '\.' (dot)
.El
.RE

.SH "EXAMPLES"

.SS "Single package"
.PP
An \fBalpm\-package\fP `\f[CR]example\fP` in a repository named `\f[CR]core\fP` is of architecture `\f[CR]x86_64\fP` and present in version `\f[CR]33\-1\fP`\.
The package is the sole output from a package build process using an \fBalpm\-source\-repo\fP at the tag `\f[CR]33\-1\fP`\.
The tag points at the commit with the SHA\-1 hash digest `\f[CR]0685197a7fdc13a91e1b9184c2759a5bf222210f\fP`\.
.PP
The file `\f[CR]core\-x86_64/example\fP` in the \fBalpm\-state\-repo\fP contains the following data:
.RS
.PP
.nf
example 33\-1 33\-1 0685197a7fdc13a91e1b9184c2759a5bf222210f
.fi
.RE

.SS "Single package with version normalization"
.PP
The package `\f[CR]example\fP` in a repository named `\f[CR]extra\-testing\fP` is of architecture `\f[CR]x86_64\fP` and present in version `\f[CR]17:4\.3\.2\-10\fP`\.
The package is the sole output from a package build process using an \fBalpm\-source\-repo\fP at the tag `\f[CR]17\-4\.3\.2\-10\fP`\.
The tag points at the commit with the SHA\-1 hash digest `\f[CR]e4f06701c4ff5cda811a5663e83cf966a81f42e0\fP`\.
.PP
The file `\f[CR]extra\-testing\-x86_64/example\fP` in the \fBalpm\-state\-repo\fP contains the following data:
.RS
.PP
.nf
example 17:4\.3\.2\-10 17\-4\.3\.2\-10 e4f06701c4ff5cda811a5663e83cf966a81f42e0
.fi
.RE

.SS "Split package"
.PP
The \fBalpm\-packages\fP `\f[CR]example\-a\fP` and `\f[CR]example\-b\fP` in a repository named `\f[CR]core\fP` are of architecture `\f[CR]x86_64\fP` and are both present in version `\f[CR]1\.0\.0\-1\fP`\.
The packages are both the output of a package build process using an \fBalpm\-source\-repo\fP at the tag `\f[CR]1\.0\.0\-1\fP`\.
The tag points at the commit with the SHA\-1 hash digest `\f[CR]0685197a7fdc13a91e1b9184c2759a5bf222210f\fP`\.
The \fBPKGBUILD\fP in the \fBalpm\-source\-repo\fP uses `\f[CR]example\-base\fP` as \fBpkgbase\fP\.
.PP
The file `\f[CR]core\-x86_64/example\-base\fP` in the \fBalpm\-state\-repo\fP contains the following data:
.RS
.PP
.nf
example\-base 1\.0\.0\-1 1\.0\.0\-1 0685197a7fdc13a91e1b9184c2759a5bf222210f
.fi
.RE

.SH "SEE ALSO"
.PP
\fBgit\fP(1), \fBPKGBUILD\fP(5), \fBalpm\-architecture\fP(7), \fBalpm\-package\fP(7), \fBalpm\-package\-base\fP(7), \fBalpm\-package\-name\fP(7), \fBalpm\-package\-version\fP(7), \fBalpm\-repo\fP(7), \fBalpm\-repo\-database\fP(7), \fBalpm\-repo\-name\fP(7), \fBalpm\-source\-repo\fP(7), \fBalpm\-split\-package\fP(7), \fBdevtools\fP(7),

.SH "NOTES"
.RS
.Bl
.IP 1. 4
\fBdbscripts\fP
.sp
https://gitlab\.archlinux\.org/archlinux/dbscripts/
.El
.RE