New global option --root

* bin/eselect.in: New global option --root.
(es_do_help): Document it.
* doc/user-guide.txt:
* man/eselect.1: Document the --root option.

Signed-off-by: Ulrich Müller <ulm@gentoo.org>

4 files changed, 32 insertions, 6 deletions

diff --git a/ChangeLog b/ChangeLog
index 2a8be3d..0f0579d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2022-01-08  Ulrich Müller  <ulm@gentoo.org>
+
+	* bin/eselect.in: New global option --root.
+	(es_do_help): Document it.
+	* doc/user-guide.txt:
+	* man/eselect.1: Document the --root option.
+
 2022-01-07  Ulrich Müller  <ulm@gentoo.org>
 
 	* modules/profile.eselect (set_symlink): Don't call canonicalise
diff --git a/bin/eselect.in b/bin/eselect.in
index 5d3fc9b..3422197 100755
--- a/bin/eselect.in
+++ b/bin/eselect.in
@@ -1,6 +1,6 @@
 #!@BASH@
 # -*-eselect-*-  vim: ft=eselect
-# Copyright (c) 2005-2020 Gentoo Authors
+# Copyright (c) 2005-2022 Gentoo Authors
 #
 # This file is part of the 'eselect' tools framework.
 #
@@ -88,6 +88,8 @@ es_do_help() {
 	write_kv_list_entry "--brief" "Make output shorter"
 	write_kv_list_entry "--colour=<yes|no|auto>" \
 		"Enable or disable colour output (default 'auto')"
+	write_kv_list_entry "--root=<path>" \
+		"The target root path for eselect's operations"
 	echo
 	# display all available eselect modules
 	do_action modules list
@@ -147,6 +149,11 @@ while [[ ${1##--} != "$1" ]]; do
 			[[ -z ${action} ]] || die -q "Too many parameters"
 			action=${1##--}
 			;;
+		root=*|root)
+			# set ROOT and recalculate EROOT
+			ROOT=${1#*=}
+			EROOT="${ROOT%${EPREFIX:+/}}${EPREFIX}"
+			;;
 		"")
 			# -- indicates end of options
 			shift
diff --git a/doc/user-guide.txt b/doc/user-guide.txt
index 8ec35c4..16c2629 100644
--- a/doc/user-guide.txt
+++ b/doc/user-guide.txt
@@ -91,10 +91,14 @@ eselect should be called as shown below: ::
         eselect [<global-options>] <module> <action> <options>
 
 eselect features consistently named actions among most of its modules.
-There are only two global options as of now; --brief, which makes
+There are only three global options as of now; --brief, which makes
 eselect's output shorter (e.g., to use it as input for other programs);
-and --colour, which controls coloured output. The following are standard
-action names -- each module may provide a subset of these actions:
+--colour, which controls coloured output; and --root, which specifies
+the path that eselect should use as the target root filesystem for its
+operations.
+
+The following are standard action names -- each module may provide a
+subset of these actions:
 
 help
     Print the module's help screen.
diff --git a/man/eselect.1 b/man/eselect.1
index 22a2fcb..fad2aac 100644
--- a/man/eselect.1
+++ b/man/eselect.1
@@ -1,8 +1,8 @@
 .\" -*- coding: utf-8 -*-
-.\" Copyright 2005-2020 Gentoo Authors
+.\" Copyright 2005-2022 Gentoo Authors
 .\" Distributed under the terms of the GNU GPL version 2 or later
 .\"
-.TH ESELECT 1 "October 2011" "Gentoo Linux" eselect
+.TH ESELECT 1 "January 2022" "Gentoo Linux" eselect
 .SH NAME
 eselect \- Gentoo's multi\-purpose configuration and management tool
 .SH SYNOPSIS
@@ -32,6 +32,14 @@ The default is
 .BR auto ,
 for which colour output is enabled only if standard output is
 connected to a terminal.
+.TP
+.BI \-\-root= path
+The
+.I path
+that eselect should use as the target root filesystem for its operations.
+If not specified, the value of the
+.I ROOT
+environment variable is used as a default.
 .SH BUILT-INS
 .TP
 .B help