From: Jacob Bachmeyer <jcb@gnu.org>
Date: Sun, 14 May 2023 04:00:32 +0000 (-0500)
Subject: Add documentation for "split-zone" keymaster command to manual
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=9518071335613a8d630e65b6d90ca2823765a248;p=gatekeeper.git

Add documentation for "split-zone" keymaster command to manual
---

diff --git a/doc/gatekeeper.texi b/doc/gatekeeper.texi
index 2003cfc..a473716 100644
--- a/doc/gatekeeper.texi
+++ b/doc/gatekeeper.texi
@@ -898,6 +898,41 @@ Generate a new key index.  This command is particularly useful after
 performing some operation directly on the keyrings to realign the key
 index with the keyrings.
 
+@subsection Zone Reorganization
+
+@quotation
+@t{keymaster.pl -z @var{source} split-zone @var{destination}}
+@end quotation
+
+Update configuration and state information after packages have been
+moved from one zone to another, separate zones that have previously
+shared configuration, or merge configuration and state information to
+combine zones.
+
+This tool requires both the global @option{--zone} option and a
+destination zone as a positional argument.  Both zones must be defined
+in the configuration, and must have distinct public (@code{publicdir})
+directories.  Additionally, at least one of the configuration
+(@code{pkgconfdir}) or state (@code{pkgstatedir}) directories must be
+different between the two zones.
+
+This tool examines the sets of packages in the public directories, and
+transfers package trees from the source zone configuration tree to the
+destination zone configuration tree to match, then transfers the
+corresponding directive timestamp records similarly.  Both zones must
+be using the same directive timestamp database format for this last
+transfer to occur.
+
+More generally, this tool can also be used to combine or selectively
+combine zones, or generally to move package configuration and history
+between zones.  First, move the public file tree for each package,
+then use this tool to move the configuration and state information.
+
+This tool will refuse to touch a package that appears in both source
+and destination zones, instead issuing a warning that the package was
+ignored.
+
+
 @node Operation, Copying Conditions, Configuration, Top
 @chapter Operation