add --sysroot option

--root is not sufficient to properly operate on a mounted guest system.
Using --root still uses the host system's configuration and there is no
way to correctly use the guest configuration without manually modifying
any Include directives.  --sysroot provides an easier way to operate on
a guest system by chrooting immediately after option parsing before
configuration parsing or performing any operations.  It is currently
limited to the root user, but that's enough for restoring a guest system
to a working state, which is the primary intended use case.

Signed-off-by: Andrew Gregory <andrew.gregory.8@gmail.com>

1 files changed, 9 insertions, 2 deletions

diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt
index f01f4aa4..d670e82a 100644
--- a/doc/pacman.8.txt
+++ b/doc/pacman.8.txt
@@ -136,11 +136,12 @@ Options
 *-r, \--root* <path>::
 	Specify an alternative installation root (default is `/`). This should
 	not be used as a way to install software into `/usr/local` instead of
-	`/usr`. This option is used if you want to install a package on a
-	temporarily mounted partition that is "owned" by another system.
+	`/usr`.
 	*NOTE*: If database path or log file are not specified on either the
 	command line or in linkman:pacman.conf[5], their default location will
 	be inside this root path.
+	*NOTE*: This option is not suitable for performing operations on a mounted
+	guest system. See '\--sysroot' instead.
 
 *-v, \--verbose*::
 	Output paths such as as the Root, Conf File, DB Path, Cache Dirs, etc.
@@ -197,6 +198,12 @@ Options
 	Disable defaults for low speed limit and timeout on downloads. Use this
 	if you have issues downloading files with proxy and/or security gateway.
 
+*\--sysroot* <dir>::
+	Specify an alternative system root.  Pacman will chroot and chdir into the
+	system root prior to running. This allows mounted guest systems to be
+	properly operated on. Any other paths given will be interpreted as relative
+	to the system root. Requires root privileges.
+
 
 Transaction Options (apply to '-S', '-R' and '-U')
 --------------------------------------------------