From 8690fc732b5cb61caa44091f52335783c6e1e77e Mon Sep 17 00:00:00 2001
From: Joachim Wiberg <troglobit@gmail.com>
Date: Tue, 10 May 2022 08:03:36 +0200
Subject: [PATCH] Fix #263: document confusing `initctl reload foo` command

What a ride, apparently we support restarting run/tasks in the same
runlevel they have already started once in.  Still unsure if adding
support for reloading a particular Finit .conf file for a service
should be in the context of this command (it isn't now).  Maybe it
is better left as a future expansion when we switch to the new .conf
format?

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
---
 README.md     |  4 +++-
 man/initctl.8 | 19 ++++++++++++++++++-
 src/initctl.c |  5 +++--
 3 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 2111528f..6b477749 100644
--- a/README.md
+++ b/README.md
@@ -451,7 +451,9 @@ Commands:
   log      [NAME]           Show ten last Finit, or NAME, messages from syslog
   start    <NAME>[:ID]      Start service by name, with optional ID
   stop     <NAME>[:ID]      Stop/Pause a running service by name
-  reload   <NAME>[:ID]      Reload service by name (SIGHUP or restart)
+  reload   <NAME>[:ID]      Reload service as if .conf changed (SIGHUP or restart)
+                            This allows restart of run/tasks that have already run
+                            Note: Finit .conf file(s) are *not* reloaded!
   restart  <NAME>[:ID]      Restart (stop/start) service by name
   status   <NAME>[:ID]      Show service status, by name
   status                    Show status of services, default command
diff --git a/man/initctl.8 b/man/initctl.8
index e3d87828..08cd3536 100644
--- a/man/initctl.8
+++ b/man/initctl.8
@@ -139,7 +139,24 @@ Start service by name, with optional ID, e.g.,
 .It Nm Ar stop Cm NAME[:ID]
 Stop/Pause a running service by name
 .It Nm Ar reload Cm NAME[:ID]
-Reload service by name (SIGHUP or restart)
+Reload service as if its configuration had changed.  Internally,
+.Nm finit
+marks the named service as "dirty" and turns the state machine,
+resulting in a SIGHUP or restart of (at least) the named service.
+Any dependant services are also restarted.
+.Pp
+.Sy Note:
+no .conf file is reloaded with this variant of the command.  Essentially
+it is the same as calling
+.Cm restart .
+Except for two things:
+.Bl -enum -offset indent -compact
+.It
+if the service supports HUP, it's signaled instead of stop-started, and
+.It
+it allows restarting run/task in the same runlevel -- which is otherwise
+restricted
+.El
 .It Nm Ar signal Cm NAME:[ID] S
 Send signal S to service, by name.
 .Cm S
diff --git a/src/initctl.c b/src/initctl.c
index ee353609..d3c9674e 100644
--- a/src/initctl.c
+++ b/src/initctl.c
@@ -1015,7 +1015,6 @@ static int usage(int rc)
 			"  reload                    Reload   " FINIT_CONF " (activate changes)\n");
 
 	fprintf(stderr,
-//		"  reload   <NAME>[:ID]      Reload (SIGHUP) service by name\n"  
 		"\n"
 		"  cond     set   <COND>     Set (assert) user-defined condition     +usr/COND\n"
 		"  cond     get   <COND>     Get status of user-defined condition, see $? and -v\n"
@@ -1026,7 +1025,9 @@ static int usage(int rc)
 		"  log      [NAME]           Show ten last Finit, or NAME, messages from syslog\n"
 		"  start    <NAME>[:ID]      Start service by name, with optional ID\n"
 		"  stop     <NAME>[:ID]      Stop/Pause a running service by name\n"
-		"  reload   <NAME>[:ID]      Reload service by name (SIGHUP or restart)\n"
+		"  reload   <NAME>[:ID]      Reload service as if .conf changed (SIGHUP or restart)\n"
+		"                            This allows restart of run/tasks that have already run\n"
+		"                            Note: Finit .conf file(s) are *not* reloaded!\n"
 		"  restart  <NAME>[:ID]      Restart (stop/start) service by name\n"
 		"  signal   <NAME>[:ID] <S>  Send signal S to service by name, with optional ID\n"
 		"  ident    [NAME]           Show matching identities for NAME, or all\n"