Add get_repo_revision_history function and repo_revisions file

The history of synced revisions is provided by a new
get_repo_revision_history function and corresponding
/var/lib/portage/repo_revisions file, with history
limit currently capped at 25 revisions. If a change
is detected and the current process has permission
to update the repo_revisions file, then the file will
be updated with any newly detected revisions.
For volatile repos the revisions may be unordered,
which makes them unusable for the purposes of the
revision history, so the revisions of volatile repos
are not tracked. This functions detects revisions
which are not yet visible to the current process due
to the sync-rcu option.

The emaint revisions --purgerepos and --purgeallrepos
options allow revisions for some or all repos to be
easily purged from the history. For example, the
emerge-webrsync script uses this emaint commmand to
purge the revision history of the gentoo repo when
the emerge-webrsync --revert option is used to roll
back to a previous snapshot:

    emaint revisions --purgerepos="${repo_name}"

Bug: https://bugs.gentoo.org/924772
Signed-off-by: Zac Medico <zmedico@gentoo.org>

2 files changed, 32 insertions, 1 deletions

diff --git a/man/emaint.1 b/man/emaint.1
index 2abba9d47..86d5e8973 100644
--- a/man/emaint.1
+++ b/man/emaint.1
@@ -1,4 +1,4 @@
-.TH "EMAINT" "1" "Feb 2021" "Portage @VERSION@" "Portage"
+.TH "EMAINT" "1" "Mar 2024" "Portage @VERSION@" "Portage"
 .SH NAME
 emaint \- performs package management related system health checks and maintenance
 .SH SYNOPSIS
@@ -54,6 +54,11 @@ Perform package move updates for installed packages.
 .br
 OPTIONS: check, fix
 .TP
+.BR revisions
+Purge repo_revisions history file.
+.br
+OPTIONS: purgerepos, purgeallrepos
+.TP
 .BR sync
 Perform sync actions on specified repositories.
 .br
@@ -86,6 +91,13 @@ deleted.
 .TP
 .BR \-y ", " \-\-yes
 Do not prompt for emerge invocations.
+.SH OPTIONS revisions command only
+.TP
+.BR \-\-purgeallrepos
+Purge revisions for all repos.
+.TP
+.BR \-\-purgerepos \ \fIREPO\fR
+Purge revisions for the specified repo(s).
 .SH OPTIONS sync command only
 .TP
 .BR \-a ", " \-\-auto
@@ -121,6 +133,10 @@ Contains the paths and md5sums of all the config files being tracked.
 .B /var/lib/portage/failed-merges
 Contains the packages and timestamps of any failed merges being cleaned from
 the system, and to be re-emerged.
+.TP
+.B /var/lib/portage/repo_revisions
+Contains the most recent repository revisions obtained via either
+\fBemaint sync\fR or \fBemerge \-\-sync\fR.
 .SH "SEE ALSO"
 .BR emerge (1),
 .BR portage (5)
diff --git a/man/portage.5 b/man/portage.5
index 3b8329bfb..66437d8f8 100644
--- a/man/portage.5
+++ b/man/portage.5
@@ -134,6 +134,7 @@ database to track installed packages
 .BR /var/lib/portage/
 .nf
 config
+repo_revisions
 world
 world_sets
 .fi
@@ -1901,6 +1902,20 @@ Hashes which are used to determine whether files in config protected
 directories have been modified since being installed.  Files which have not
 been modified will automatically be unmerged.
 .TP
+.BR repo_revisions
+Contains the most recent repository revisions obtained via either
+\fBemaint sync\fR or \fBemerge \-\-sync\fR. The format is a JSON
+object which maps a repo name to list of revisions in descending
+order by time. In cases when revisions are not ordered by time,
+the volatile attribute should be set in \fBrepos.conf\fR in order
+to prevent unordered revisions from being stored in the
+repo_revisions file. The \fBemaint revisions\fR command can be
+used to purge revisions for specific repos, which should be done
+in any case when there is a need to roll back to an older
+revision (the \fBemerge\-webrsync \-\-revert\fR option calls
+\fBemaint revisions\fR in order to purge all revision history
+for the repository).
+.TP
 .BR world
 Every time you emerge a package, the package that you requested is
 recorded here.  Then when you run `emerge world \-up`, the list of