Add `--zl=N` opt & improve its docs.

diff --git a/NEWS.md b/NEWS.md
index 5b8946aafdf8d93d629af27500de0091538a1373..a2d9f0f0fefa71d24067972807f681ca5407bdb1 100644 (file)
--- a/NEWS.md
+++ b/NEWS.md
@@ -29,6 +29,10 @@ Protocol: 31 (unchanged)
 
 ### ENHANCEMENTS:
 
+ - The use of `--backup-dir=STR` now implies `--backup`.
+
+ - Added `--zl=NUM` as a short-hand for `--compress-level=NUM`.
+
  - Added `--early-input=FILE` option that allows the client to send some
    data to a daemon's (optional) "early exec" script on its stdin.
 

diff --git a/options.c b/options.c
index 961cd48c0c6ef15edb4bd648737825b590b2baec..73d5ed47c93635500644c0c5c929918ee5c1c3b0 100644 (file)
--- a/options.c
+++ b/options.c
@@ -945,6 +945,7 @@ static struct poptOption long_options[] = {
   {"zc",               0,  POPT_ARG_STRING, &compress_choice, 0, 0, 0 },
   {"skip-compress",    0,  POPT_ARG_STRING, &skip_compress, 0, 0, 0 },
   {"compress-level",   0,  POPT_ARG_INT,    &do_compression_level, 0, 0, 0 },
+  {"zl",               0,  POPT_ARG_INT,    &do_compression_level, 0, 0, 0 },
   {0,                 'P', POPT_ARG_NONE,   0, 'P', 0, 0 },
   {"progress",         0,  POPT_ARG_VAL,    &do_progress, 1, 0, 0 },
   {"no-progress",      0,  POPT_ARG_VAL,    &do_progress, 0, 0, 0 },

diff --git a/rsync.1.md b/rsync.1.md
index 9acaed3c5a69a8c29ea89972f66745263c974422..71f1e88a8e1b738f820cf46bd8e628957195b2d6 100644 (file)
--- a/rsync.1.md
+++ b/rsync.1.md
@@ -2311,11 +2311,40 @@ your home directory (remove the '=' for that).
     enough to handle a compression negotiation list, the list is silently
     ignored unless it contains the string "FAIL".
 
-0.  `--compress-level=NUM`
+0.  `--compress-level=NUM`, `--zl=NUM`
 
-    Explicitly set the compression level to use (see `--compress`) instead of
-    letting it default.  If NUM is non-zero, the `--compress` option is
-    implied.
+    Explicitly set the compression level to use (see `--compress`, `-z`)
+    instead of letting it default.  The `--compress` option is implied as long
+    as the level chosen is not a "don't compress" level for the compression
+    algorithm that is in effect (e.g. zlib compression treats level 0 as
+    "off").
+
+    The level values vary depending on the checksum in effect.  Because rsync
+    will negotiate a checksum choice by default when the remote rsync is new
+    enough, it can be good to combine this option with a `--compress-choice`
+    (`--zc`) option unless you're sure of the choice in effect.  For example:
+
+    >     rsync -aiv --zc=zstd --zl=22 host:src/ dest/
+
+    For zlib & zlibx compression, the valid values are from 1 to 9 with 6 being
+    the default.  Specifying 0 turns compression off, and specifying -1 chooses
+    the default of 6.
+
+    For zstd compression, the valid values are from -131072 to 22 with 3 being
+    the default. Specifying 0 chooses the default of 3.
+
+    For lz4 compression, there are no levels available, so the level is always
+    0.
+
+    If you specify a too-large or too-small value, the number is silently
+    limited to a valid value.  This allows you to specify something like
+    `--zl=999999999` and be assured that you'll end up with the maximum
+    compression level no matter what algorithm was chosen.
+
+    If you want to know the compression level that is in effect, specify the
+    `--debug=nstr` to see the "negotiated string" results.  This will report
+    something like "`Client compress: zstd (level 3)`" (along with the checksum
+    choice in effect).
 
 0.  `--skip-compress=LIST`