Change new stderr options to `--stderr=MODE`.

3 files changed, 48 insertions, 28 deletions

diff --git a/NEWS.md b/NEWS.md
index 1f58f825..5f5a6e76 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -45,9 +45,18 @@
  - Added `--mkpath` option to tell rsync that it should create a non-existing
    path component of the destination arg.
 
- - Added `--errors2stdout` (the new default) and `--msgs2protocol` (the old
-   default).  The new output idiom should help error messages get to the user
-   more quickly when doing a push (which includes local copying).
+ - Added `--stderr=errors|all|client` to replace the `--msgs2stderr` and
+   `--no-msgs2stderr` options (which are still accepted).  The default use of
+   stderr was changed to be `--stderr=errors` where all the processes that have
+   stderr available output directly to stderr, which should help error messages
+   get to the user more quickly, especially when doing a push (which includes
+   local copying).  This also allows rsync to exit quickly when a receiver
+   failure occurs, since rsync doesn't need to try to keep the connection alive
+   long enough for the fatal error to go from the receiver to the generator to
+   the sender.  The old default can be requested via `--stderr=client`.  Also
+   changed is that a non-default stderr mode is conveyed to the remote rsync
+   (using the older option names) instead of requiring the user to use
+   `--remote-option` (`-M`) to tell the remote rsync what to do.
 
  - Added the ability to specify "@netgroup" names to the `hosts allow` and
    `hosts deny` daemon parameters.  This is a finalized version of the
@@ -56,14 +65,6 @@
  - Output file+line info on out-of-memory & overflow errors while also avoiding
    the output of alternate build-dir path info that is not useful to the user.
 
- - Improve the error handling for local and remote-shell transfers by sending
-   error messages directly to stderr, even on the remote side (instead of
-   having an error wind its way through the pipelined backlog).  This also
-   allows rsync to exit quickly when a receiver failure occurs, since rsync
-   doesn't need to try to keep the connection alive long enough for the fatal
-   error to go from the receiver to the generator to the sender.  To disable
-   this new default you can use the `--no-msgs2stderr` option.
-
  - Change configure to know that Cywin supports Linux xattrs.
 
  - Improved the testsuite on FreeBSD & Cygwin.
diff --git a/options.c b/options.c
index 3304cbae..36e88621 100644
--- a/options.c
+++ b/options.c
@@ -794,7 +794,7 @@ enum {OPT_SERVER = 1000, OPT_DAEMON, OPT_SENDER, OPT_EXCLUDE, OPT_EXCLUDE_FROM,
       OPT_INCLUDE, OPT_INCLUDE_FROM, OPT_MODIFY_WINDOW, OPT_MIN_SIZE, OPT_CHMOD,
       OPT_READ_BATCH, OPT_WRITE_BATCH, OPT_ONLY_WRITE_BATCH, OPT_MAX_SIZE,
       OPT_NO_D, OPT_APPEND, OPT_NO_ICONV, OPT_INFO, OPT_DEBUG, OPT_BLOCK_SIZE,
-      OPT_USERMAP, OPT_GROUPMAP, OPT_CHOWN, OPT_BWLIMIT,
+      OPT_USERMAP, OPT_GROUPMAP, OPT_CHOWN, OPT_BWLIMIT, OPT_STDERR,
       OPT_OLD_COMPRESS, OPT_NEW_COMPRESS, OPT_NO_COMPRESS,
       OPT_STOP_AFTER, OPT_STOP_AT,
       OPT_REFUSED_BASE = 9000};
@@ -808,9 +808,8 @@ static struct poptOption long_options[] = {
   {"no-v",             0,  POPT_ARG_VAL,    &verbose, 0, 0, 0 },
   {"info",             0,  POPT_ARG_STRING, 0, OPT_INFO, 0, 0 },
   {"debug",            0,  POPT_ARG_STRING, 0, OPT_DEBUG, 0, 0 },
-  {"errors2stderr",    0,  POPT_ARG_VAL,    &msgs2stderr, 2, 0, 0 },
+  {"stderr",           0,  POPT_ARG_STRING, 0, OPT_STDERR, 0, 0 },
   {"msgs2stderr",      0,  POPT_ARG_VAL,    &msgs2stderr, 1, 0, 0 },
-  {"msgs2protocol",    0,  POPT_ARG_VAL,    &msgs2stderr, 0, 0, 0 },
   {"no-msgs2stderr",   0,  POPT_ARG_VAL,    &msgs2stderr, 0, 0, 0 },
   {"quiet",           'q', POPT_ARG_NONE,   0, 'q', 0, 0 },
   {"motd",             0,  POPT_ARG_VAL,    &output_motd, 1, 0, 0 },
@@ -2094,6 +2093,24 @@ int parse_arguments(int *argc_p, const char ***argv_p)
 			break;
 #endif
 
+		case OPT_STDERR: {
+			int len;
+			arg = poptGetOptArg(pc);
+			len = strlen(arg);
+			if (len && strncmp("errors", arg, len) == 0)
+				msgs2stderr = 2;
+			else if (len && strncmp("all", arg, len) == 0)
+				msgs2stderr = 1;
+			else if (len && strncmp("client", arg, len) == 0)
+				msgs2stderr = 0;
+			else {
+				snprintf(err_buf, sizeof err_buf,
+					"--stderr mode \"%s\" is not one of errors, all, or client\n", arg);
+				return 0;
+			}
+			break;
+		}
+
 		default:
 			/* A large opt value means that set_refuse_options()
 			 * turned this option off. */
diff --git a/rsync.1.md b/rsync.1.md
index cb26b5af..08ea68bc 100644
--- a/rsync.1.md
+++ b/rsync.1.md
@@ -334,9 +334,7 @@ detailed description below for a complete description.
 --verbose, -v            increase verbosity
 --info=FLAGS             fine-grained informational verbosity
 --debug=FLAGS            fine-grained debug verbosity
---errors2stderr          output errors directly to stderr (the default)
---msgs2stderr            output all messages directly to stderr
---msgs2protocol          forward all messages via the protocol stream
+--stderr=e|a|c           change stderr output mode (default: errors)
 --quiet, -q              suppress non-error messages
 --no-motd                suppress daemon-mode MOTD
 --checksum, -c           skip based on checksum, not mod-time & size
@@ -584,7 +582,7 @@ your home directory (remove the '=' for that).
     >     rsync -avvv --debug=none src/ dest/
     >     rsync -avA --del --debug=del2,acl src/ dest/
 
-    Note that some debug messages will only be output when `--msgs2stderr` is
+    Note that some debug messages will only be output when `--stderr=all` is
     specified, especially those pertaining to I/O and buffer debugging.
 
     Beginning in 3.2.0, this option is no longer auto-forwared to the server
@@ -596,18 +594,20 @@ your home directory (remove the '=' for that).
 
     >     rsync -aiv {-M,}--debug=del2 src/ dest/
 
-0.  `--errors2stderr`, `--msgs2stderr`, `--msgs2protocol`
+0.  `--stderr=errors|all|client`
 
-    Rsync handles messages in 3 possible ways:
+    This option controls which processes output to stderr and if info messages
+    are also changed to stderr.  The mode strings can be abbreviaated, so feel
+    free to use a single letter value.  The 3 possible choices are:
 
-    - `--errors2stderr` (the default) causes all the rsync processes to send an
+    - `errors` - (the default) causes all the rsync processes to send an
       error directly to stderr, even if the process is on the remote side of
       the transfer.  Info messages are sent to the client side via the protocol
       stream.  If stderr is not available (i.e. when directly connecting with a
       daemon via a socket) errors fall back to being sent via the protocol
-      stream.  This option and the default are new for version 3.2.3.
+      stream.
 
-    - `--msgs2stderr` causes all rsync messages (info and error) to get written
+    - `all` - causes all rsync messages (info and error) to get written
       directly to stderr from all (possible) processes.  This causes stderr to
       become line-buffered (instead of raw) and eliminates the ability to
       divide up the info and error messages by file handle.  For those doing
@@ -616,17 +616,19 @@ your home directory (remove the '=' for that).
       a deadlock bug hanging things up).  It also enables the outputting of some
       I/O related debug messages.
 
-    - `--msgs2protocol` causes all rsync messages to be sent to the client side
+    - `client` - causes all rsync messages to be sent to the client side
       via the protocol stream.  One client process outputs all messages, with
       errors on stderr and info messages on stdout.  This **was** the default
       in older rsync versions, but can cause error delays when a lot of
       transfer data is ahead of the messages.  If you're pushing files to an
-      older rsync, you may want to use `--msgs2stderr` since that option has
+      older rsync, you may want to use `--stderr=all` since that idiom has
       been around for several releases.
 
-    Starting with rsync 3.2.3, the `--msgs2stderr` and `--msgs2protocol`
-    options are forwarded to the remote rsync, though the latter is conveyed
-    using the backward-compatible `--no-msgs2stderr` option.
+    This option was added in rsync 3.2.3.  This version also began the
+    forwarding of a non-default setting to the remote side, though rsync uses
+    the backward-compatible options `--msgs2stderr` and `--no-msgs2stderr` to
+    represent the `all` and `client` settings, respectively.  A newer rsync
+    will continue to accept these older option names to maintain compatibility.
 
 0.  `--quiet`, `-q`