Repository: borgbackup/borg

Issue:
--recompress option is counter intuitive
Have you checked borgbackup docs, FAQ, and open Github issues?: **Yes**
Is this a BUG / ISSUE report or a QUESTION?: **Issue/Question**
Borg version: **1.1.11**
(Other information omitted since not relevant to issue)

I appreciate that `recreate` is an experimental feature and is likely to undergo heavy development until full release (I'm looking forward to the proposed changes in #3631 in particular!). However, the following issue is a UI issue which is perhaps best fixed whist `recreate` is still marked "experimental" and backwards compatibility is not as important.

Currently the default `MODE` when `--recompress`ing is `never`. This is is so counter intuitive that _even the documentation_ gets it wrong:

In the documentation (`man borg-recreate`) under `Examples` it currently states that
```
Create a backup with little but fast compression
$ borg create /mnt/backup::archive /some/files --compression lz4
# Then compress it - this might take longer, but the backup has already completed,
# so no inconsistencies from a long-running backup job.
$ borg recreate /mnt/backup::archive --recompress --compression zlib,9
```
however, according to discussions in #3617, and the merge #3676 (which reflects current documentation), I believe the second borg command would *not* recompress the data (since the default `MODE` is `never`)? I think the example *should* be
```
$ borg recreate /mnt/backup::archive --recompress if-different --compression zlib,9
```
If I have understood correctly, there is no difference between `if-different` and `always` in this context because the previous compression was `lz4` and now it is `zlib`?

To mitigate this, I would suggest that borg should throws an error if no `MODE` is specified.

In fact, it might be worth going one step further, and removing the `never` `MODE` entirely. I'm not sure in which context
```
$ borg recreate $REPO::$ARCHIVE --recompress never [...]
```
makes sense? What is the difference between this, and
```
$ borg recreate $REPO::$ARCHIVE [...]
```
? Perhaps it to underline the fact that if an archive is `recreate`d without `--compression`, then the previous compression algorithms and levels are used? If so, I think this should be documented more clearly.

However, I appreciate that, for backwards compatibility (even as an experimental feauture), this may not be feasible. As a compromise, I would create a warning in the style of the experimental feature warning:
```
recreate is an experimental feature.
WARNING: Currently borg will not perform any recompression even though '--compression' was passed since no MODE was given.
Type 'YES' if you understand this and want to continue: YES
```
The rationale for the proposed changes is that --- before changes in #3631 are implemented -- it could be a very time-wasting endeavor to `recreate --compress --compression L[,C]` only to find out ~24 hrs later that no compression took place.

Further, I would stress the importance of the `MODE` in the first line of the description. That is, change
```
recompress data chunks according to --compression
```
to
```
recompress data chunks according to MODE and --compression
```

Thank you for your hard work on this project.

(Edited for clarification and wording)


Discussion:

Resolving patch:
diff --git a/src/borg/archiver.py b/src/borg/archiver.py
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -4104,15 +4104,16 @@ def define_borg_mount(parser):
                                         '"borg help compression" command for details.')
         archive_group.add_argument('--recompress', metavar='MODE', dest='recompress', nargs='?',
                                    default='never', const='if-different', choices=('never', 'if-different', 'always'),
-                                   help='recompress data chunks according to ``--compression``. '
-                                        'MODE `if-different`: '
-                                        'recompress if current compression is with a different compression algorithm '
-                                        '(the level is not considered). '
-                                        'MODE `always`: '
-                                        'recompress even if current compression is with the same compression algorithm '
-                                        '(use this to change the compression level). '
-                                        'MODE `never` (default): '
-                                        'do not recompress.')
+                                   help='recompress data chunks according to `MODE` and ``--compression``. '
+                                        'Possible modes are '
+                                        '`if-different`: recompress if current compression is with a different '
+                                        'compression algorithm (the level is not considered); '
+                                        '`always`: recompress even if current compression is with the same '
+                                        'compression algorithm (use this to change the compression level); and '
+                                        '`never`: do not recompress (use this option to explicitly prevent '
+                                        'recompression). '
+                                        'If no MODE is given, `if-different` will be used. '
+                                        'Not passing --recompress is equivalent to "--recompress never".')
         archive_group.add_argument('--chunker-params', metavar='PARAMS', dest='chunker_params',
                                    type=ChunkerParams, default=CHUNKER_PARAMS,
                                    help='specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, '


Test patch: