From a065d815b1153ea38c58d5f64a2bfdfe31d330a4 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Sat, 20 Dec 2025 12:53:35 +0000
Subject:  Consistency of --force-essential option

---
 doc/s6-rc-set-change.html | 16 ++++++++++++----
 doc/s6-rc-set-fix.html    |  4 ++--
 2 files changed, 14 insertions(+), 6 deletions(-)

(limited to 'doc')

diff --git a/doc/s6-rc-set-change.html b/doc/s6-rc-set-change.html
index 0253af4..6e45c2e 100644
--- a/doc/s6-rc-set-change.html
+++ b/doc/s6-rc-set-change.html
@@ -26,7 +26,7 @@ the <a href="repodefs.html#sub">sub</a> of some services.
 <h2> Interface </h2>
 
 <pre>
-     s6-rc-set-change [ -v <em>verbosity</em> ] [ -r <em>repo</em> ] [ -E ] [ -f | -I fail|pull|warn ] [ -n ] <em>set</em> <em>newsub</em> <em>services...</em>
+     s6-rc-set-change [ -v <em>verbosity</em> ] [ -r <em>repo</em> ] [ -E | -e ] [ -f | -I fail|pull|warn ] [ -n ] <em>set</em> <em>newsub</em> <em>services...</em>
 </pre>
 
 <ul>
@@ -48,9 +48,17 @@ error messages will be written, and 2 or more adds informational messages. </dd>
 <strong>/var/lib/s6-rc/repository</strong>.
  </dd>
 
- <dt> -E, --force-essential </dt>
- <dd> This option is necessary in order if <em>newsub</em> is <tt>always</tt>.
-Without that option, s6-rc-set-change refuses to set services to <tt>always</tt>. </dd>
+ <dt> -E, --no-force-essential </dt>
+ <dd> If a service needs to be moved to/from the <tt>always</tt> sub, fail and report
+an error. This is the default. Services marked as <em>always</em> are normally defined
+in the stores with <tt>flag-essential</tt>, and inconsistencies between essential
+services should be resolved in the stores. </dd>
+
+ <dt> -e, --force-essential </dt>
+ <dd> Move services to/from the <tt>always</tt> sub if they need to be. This option
+should only be used temporarily until the store inconsistency is fixed. Be aware that
+moving a service from <em>always</em> to <em>usable</em> or <em>masked</em> may
+result in an unbootable set. </dd>
 
  <dt> -f, --ignore-dependencies </dt>
  <dd> Change <em>services...</em> to <em>newsub</em>, but do not change any other
diff --git a/doc/s6-rc-set-fix.html b/doc/s6-rc-set-fix.html
index e8c0fb3..eae3d69 100644
--- a/doc/s6-rc-set-fix.html
+++ b/doc/s6-rc-set-fix.html
@@ -67,7 +67,7 @@ the situation by making <tt>B</tt> <em>usable</em> (if <tt>A</tt> is <em>usable<
 or <em>masked</em> (if <tt>A</tt> is <em>masked</em>). This means that fewer services
 will be started at boot time than the set initially declared. This is the default. </dd>
 
- <dt> -E, --no-force-essentials </dt>
+ <dt> -E, --no-force-essential </dt>
  <dd> If fixing a dependency inconsistency would imply moving a service down from the
 <em>always</em> sub, or up to the <em>always</em> sub, when its service definition
 directory does not declare it as essential, do not attempt fixing it and fail the operation.
@@ -75,7 +75,7 @@ This is the default. If such a situation occurs, it means that the set of servic
 provided in the <a href="repodefs.html#sub">stores</a> is not consistent, and that
 is what should be fixed. </dd>
 
- <dt> -e, --force-essentials </dt>
+ <dt> -e, --force-essential </dt>
  <dd> If fixing a dependency inconsistency would imply moving a service down from the
 <em>always</em> sub, or up to the <em>always</em> sub, when its service definition
 directory does not declare it as essential, do it, even though it goes against a
-- 
cgit v1.3.1