.\" -*- mode: troff; coding: utf-8 -*-
.TH "" "7" ""
.SH NAME
.LP
state-repo - a directory structure to track \fBA\fRrch \fBL\fRinux \fBP\fRackage \fBM\fRanagement (ALPM) package repository state.
.SH DESCRIPTION
.LP
End users gain access to ALPM based packages (see \fBalpm-package\fR) through package repositories (see \fBalpm-repo\fR).
These also contain database files describing their current state (see \fBalpm-repo-db\fR) to the end users.
.PP
An \fBalpm-state-repo\fR is used by package repository maintainers and provides a detailed view on several aspects of one or more package repositories:
.IP "\(bu" 3
The names of all \fBalpm-package-bases\fR and their respective versions currently provided in all tracked repositories.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
A reference to the git tag, as well as the fully resolved git commit hash digest in an \fBalpm-source-repo\fR, that packages with the respective \fBalpm-package-base\fR are built from.
.LP
A state-repo is maintained using repository management software (e.g. \fBdbscripts\fR [1]).
It is usually kept in a version controlled repository (e.g. \fBgit\fR) to reflect on atomic changes to the contained data in dedicated commits.
.SH FORMAT
.LP
An \fBalpm-state-repo\fR contains \fBrepository directories\fR at its root which each may contain zero or more \fBstate files\fR.
.SS
Repository directory
.LP
A repository directory represents architecture specific information about an \fBalpm-repo\fR.
Each directory name consists of an \fBalpm-repo-name\fR directly followed by a \(oq-\(cq sign, directly followed by an \fBalpm-architecture\fR, e.g.:
.LP
.EX
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
\e-- extra-x86_64
.EE
.PP
Different from an \fBalpm-repo\fR, an \fBalpm-state-repo\fR distinguishes between architecture-dependent (e.g. \f(CRx86_64\fR) and architecture-independent (i.e. \f(CRany\fR) 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\fR comprise the state of an \fBalpm-repo\fR of the same name (e.g. the directories \f(CRcore-any\fR and \f(CRcore-x86_64\fR in an \fBalpm-state-repo\fR contain data for an \fBalpm-repo\fR named \f(CRcore\fR).
.PP
Each \fBrepository directory\fR contains zero or more \fBstate files\fR.
.SS
State file
.LP
All files in a \fBrepository directory\fR are named after an \fBalpm-package-base\fR for which they provide state data.
Each \fBalpm-package-base\fR implicitly refers to one or more \fBalpm-packages\fR in the respective \fBalpm-repo\fR that the \fBrepository directory\fR targets.
.PP
A state file consists of a single line with the four components \fIpackage name\fR, \fIversion\fR, \fItag\fR and \fIdigest\fR, each separated by a space:
.IP "1." 3
\fIpackage name\fR: The \fBalpm-package-base\fR of one or more \fBalpm-packages\fR in the targeted \fBalpm-repo\fR.
This value must be identical to the name of the \fBstate file\fR!
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "2." 3
\fIversion\fR: The version of the \fBalpm-package-base\fR, formatted as an \fBalpm-package-version\fR in \fBfull\fR or \fBfull with epoch\fR variant.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "3." 3
\fItag\fR: The git tag in the \fBalpm-source-repo\fR from which all \fBalpm-packages\fR that share \fIpackage name\fR are built.
This value is based on \fIversion\fR but is subject to \fBversion normalization\fR.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "4." 3
\fIdigest\fR: The SHA-1 hash digest of the commit that \fItag\fR points at in the \fBalpm-source-repo\fR.
.SS
Version normalization
.LP
Git is not able to use certain characters in tags that are allowed in the \fBalpm-package-version\fR format.
To be able to relate the version encoded in a \fBPKGBUILD\fR or \fBSRCINFO\fR file that is part of an \fBalpm-source-repo\fR and by extension also the \fBpkgver\fR value found in a package\(cqs \fBPKGINFO\fR or \fBBUILDINFO\fR built from those sources, a tag undergoes normalization. 
.PP
The following modifications are applied in order to normalize the string:
.IP "1." 3
Replace all occurrences of \(oq:\(cq (colon) with a \(oq-\(cq (dash)
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "2." 3
Replace all occurrences of \(oq\(ti\(cq (tilde) with a \(oq.\(cq (dot)
.SH EXAMPLES
.SS
Single package
.LP
An \fBalpm-package\fR \f(CRexample\fR in a repository named \f(CRcore\fR is of architecture \f(CRx86_64\fR and present in version \f(CR33-1\fR.
The package is the sole output from a package build process using an \fBalpm-source-repo\fR at the tag \f(CR33-1\fR.
The tag points at the commit with the SHA-1 hash digest \f(CR0685197a7fdc13a91e1b9184c2759a5bf222210f\fR.
.PP
The file \f(CRcore-x86_64/example\fR in the \fBalpm-state-repo\fR contains the following data:
.LP
.EX
example 33-1 33-1 0685197a7fdc13a91e1b9184c2759a5bf222210f
.EE
.SS
Single package with version normalization
.LP
The package \f(CRexample\fR in a repository named \f(CRextra-testing\fR is of architecture \f(CRx86_64\fR and present in version \f(CR17:4.3.2-10\fR.
The package is the sole output from a package build process using an \fBalpm-source-repo\fR at the tag \f(CR17-4.3.2-10\fR.
The tag points at the commit with the SHA-1 hash digest \f(CRe4f06701c4ff5cda811a5663e83cf966a81f42e0\fR.
.PP
The file \f(CRextra-testing-x86_64/example\fR in the \fBalpm-state-repo\fR contains the following data:
.LP
.EX
example 17:4.3.2-10 17-4.3.2-10 e4f06701c4ff5cda811a5663e83cf966a81f42e0
.EE
.SS
Split package
.LP
The \fBalpm-packages\fR \f(CRexample-a\fR and \f(CRexample-b\fR in a repository named \f(CRcore\fR are of architecture \f(CRx86_64\fR and are both present in version \f(CR1.0.0-1\fR.
The packages are both the output of a package build process using an \fBalpm-source-repo\fR at the tag \f(CR1.0.0-1\fR.
The tag points at the commit with the SHA-1 hash digest \f(CR0685197a7fdc13a91e1b9184c2759a5bf222210f\fR.
The \fBPKGBUILD\fR in the \fBalpm-source-repo\fR uses \f(CRexample-base\fR as \fBpkgbase\fR.
.PP
The file \f(CRcore-x86_64/example-base\fR in the \fBalpm-state-repo\fR contains the following data:
.LP
.EX
example-base 1.0.0-1 1.0.0-1 0685197a7fdc13a91e1b9184c2759a5bf222210f
.EE
.SH SEE ALSO
.LP
\fBgit\fR(1), \fBPKGBUILD\fR(5), \fBalpm-architecture\fR(7), \fBalpm-package\fR(7), \fBalpm-package-base\fR(7), \fBalpm-package-name\fR(7), \fBalpm-package-version\fR(7), \fBalpm-repo\fR(7), \fBalpm-repo-db\fR(7), \fBalpm-repo-name\fR(7), \fBalpm-source-repo\fR(7), \fBalpm-split-package\fR(7), \fBdevtools\fR(7),
.SH NOTES
.IP "1." 3
\fBdbscripts\fR
.IP
.UR https://gitlab.archlinux.org/archlinux/dbscripts/
.UE