archiver: more consistent arguments formatting

src/borg/archiver.py

@@ -2304,32 +2304,30 @@ class Archiver:
             add_common_option('--debug', dest='log_level',
                               action='store_const', const='debug', default='warning',
                               help='enable debug output, work on log level DEBUG')
-            add_common_option('--debug-topic', dest='debug_topics',
-                              action='append', metavar='TOPIC', default=[],
+            add_common_option('--debug-topic', metavar='TOPIC', dest='debug_topics', action='append', default=[],
                               help='enable TOPIC debugging (can be specified multiple times). '
                                    'The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.')
             add_common_option('-p', '--progress', dest='progress', action='store_true',
                               help='show progress information')
             add_common_option('--log-json', dest='log_json', action='store_true',
                               help='Output one JSON object per log line instead of formatted text.')
-            add_common_option('--lock-wait', dest='lock_wait', type=int, metavar='N', default=1,
-                              help='wait for the lock, but max. N seconds (default: %(default)d).')
+            add_common_option('--lock-wait', metavar='SECONDS', dest='lock_wait', type=int, default=1,
+                              help='wait at most SECONDS for acquiring a repository/cache lock (default: %(default)d).')
             add_common_option('--show-version', dest='show_version', action='store_true',
                               help='show/log the borg version')
             add_common_option('--show-rc', dest='show_rc', action='store_true',
                               help='show/log the return code (rc)')
             add_common_option('--no-files-cache', dest='cache_files', action='store_false',
                               help='do not load/update the file metadata cache used to detect unchanged files')
-            add_common_option('--umask', dest='umask', type=lambda s: int(s, 8), default=UMASK_DEFAULT, metavar='M',
+            add_common_option('--umask', metavar='M', dest='umask', type=lambda s: int(s, 8), default=UMASK_DEFAULT,
                               help='set umask to M (local and remote, default: %(default)04o)')
-            add_common_option('--remote-path', dest='remote_path', metavar='PATH',
+            add_common_option('--remote-path', metavar='PATH', dest='remote_path',
                               help='use PATH as borg executable on the remote (default: "borg")')
-            add_common_option('--remote-ratelimit', dest='remote_ratelimit', type=int, metavar='rate',
+            add_common_option('--remote-ratelimit', metavar='RATE', dest='remote_ratelimit', type=int,
                               help='set remote network upload rate limit in kiByte/s (default: 0=unlimited)')
-            add_common_option('--consider-part-files', dest='consider_part_files',
-                              action='store_true',
+            add_common_option('--consider-part-files', dest='consider_part_files', action='store_true',
                               help='treat part files like normal files (e.g. to list/extract them)')
-            add_common_option('--debug-profile', dest='debug_profile', default=None, metavar='FILE',
+            add_common_option('--debug-profile', metavar='FILE', dest='debug_profile', default=None,
                               help='Write execution profile in Borg format into FILE. For local use a Python-'
                                    'compatible file can be generated by suffixing FILE with ".pyprof".')
 
@@ -2370,25 +2368,25 @@ class Archiver:
             filters_group = subparser.add_argument_group('Archive filters',
                                                          'Archive filters can be applied to repository targets.')
             group = filters_group.add_mutually_exclusive_group()
-            group.add_argument('-P', '--prefix', dest='prefix', type=PrefixSpec, default='', metavar='PREFIX',
+            group.add_argument('-P', '--prefix', metavar='PREFIX', dest='prefix', type=PrefixSpec, default='',
                                help='only consider archive names starting with this prefix.')
-            group.add_argument('-a', '--glob-archives', dest='glob_archives', default=None, metavar='GLOB',
+            group.add_argument('-a', '--glob-archives', metavar='GLOB', dest='glob_archives', default=None,
                                help='only consider archive names matching the glob. '
                                     'sh: rules apply, see "borg help patterns". '
                                     '``--prefix`` and ``--glob-archives`` are mutually exclusive.')
 
             if sort_by:
                 sort_by_default = 'timestamp'
-                filters_group.add_argument('--sort-by', dest='sort_by', type=SortBySpec, default=sort_by_default,
-                                           metavar='KEYS',
+                filters_group.add_argument('--sort-by', metavar='KEYS', dest='sort_by',
+                                           type=SortBySpec, default=sort_by_default,
                                            help='Comma-separated list of sorting keys; valid keys are: {}; default is: {}'
                                            .format(', '.join(HUMAN_SORT_KEYS), sort_by_default))
 
             if first_last:
                 group = filters_group.add_mutually_exclusive_group()
-                group.add_argument('--first', dest='first', metavar='N', default=0, type=int,
+                group.add_argument('--first', metavar='N', dest='first', default=0, type=int,
                                    help='consider first N archives after other filters were applied')
-                group.add_argument('--last', dest='last', metavar='N', default=0, type=int,
+                group.add_argument('--last', metavar='N', dest='last', default=0, type=int,
                                    help='consider last N archives after other filters were applied')
 
         parser = argparse.ArgumentParser(prog=self.prog, description='Borg - Deduplicated Backups',
@@ -2418,22 +2416,22 @@ class Archiver:
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
                                           help='start repository server process')
         subparser.set_defaults(func=self.do_serve)
-        subparser.add_argument('--restrict-to-path', dest='restrict_to_paths', action='append',
-                               metavar='PATH', help='restrict repository access to PATH. '
-                                                    'Can be specified multiple times to allow the client access to several directories. '
-                                                    'Access to all sub-directories is granted implicitly; PATH doesn\'t need to directly point to a repository.')
-        subparser.add_argument('--restrict-to-repository', dest='restrict_to_repositories', action='append',
-                               metavar='PATH', help='restrict repository access. Only the repository located at PATH (no sub-directories are considered) '
-                                                    'is accessible. '
-                                                    'Can be specified multiple times to allow the client access to several repositories. '
-                                                    'Unlike ``--restrict-to-path`` sub-directories are not accessible; '
-                                                    'PATH needs to directly point at a repository location. '
-                                                    'PATH may be an empty directory or the last element of PATH may not exist, in which case '
-                                                    'the client may initialize a repository there.')
+        subparser.add_argument('--restrict-to-path', metavar='PATH', dest='restrict_to_paths', action='append',
+                               help='restrict repository access to PATH. '
+                                    'Can be specified multiple times to allow the client access to several directories. '
+                                    'Access to all sub-directories is granted implicitly; PATH doesn\'t need to directly point to a repository.')
+        subparser.add_argument('--restrict-to-repository', metavar='PATH', dest='restrict_to_repositories', action='append',
+                                help='restrict repository access. Only the repository located at PATH '
+                                     '(no sub-directories are considered) is accessible. '
+                                     'Can be specified multiple times to allow the client access to several repositories. '
+                                     'Unlike ``--restrict-to-path`` sub-directories are not accessible; '
+                                     'PATH needs to directly point at a repository location. '
+                                     'PATH may be an empty directory or the last element of PATH may not exist, in which case '
+                                     'the client may initialize a repository there.')
         subparser.add_argument('--append-only', dest='append_only', action='store_true',
                                help='only allow appending to repository segment files')
-        subparser.add_argument('--storage-quota', dest='storage_quota', default=None,
-                               type=parse_storage_quota,
+        subparser.add_argument('--storage-quota', metavar='QUOTA', dest='storage_quota',
+                               type=parse_storage_quota, default=None,
                                help='Override storage quota of the repository (e.g. 5G, 1.5T). '
                                     'When a new repository is initialized, sets the storage quota on the new '
                                     'repository as well. Default: no quota.')
@@ -2549,12 +2547,12 @@ class Archiver:
         subparser.add_argument('location', metavar='REPOSITORY', nargs='?', default='',
                                type=location_validator(archive=False),
                                help='repository to create')
-        subparser.add_argument('-e', '--encryption', dest='encryption', required=True, metavar='MODE',
+        subparser.add_argument('-e', '--encryption', metavar='MODE', dest='encryption', required=True,
                                choices=('none', 'keyfile', 'repokey', 'keyfile-blake2', 'repokey-blake2', 'authenticated'),
                                help='select encryption key mode **(required)**')
         subparser.add_argument('--append-only', dest='append_only', action='store_true',
                                help='create an append-only mode repository')
-        subparser.add_argument('--storage-quota', dest='storage_quota', default=None, metavar='QUOTA',
+        subparser.add_argument('--storage-quota', metavar='QUOTA', dest='storage_quota', default=None,
                                type=parse_storage_quota,
                                help='Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.')
 
@@ -2846,8 +2844,8 @@ class Archiver:
                                help='print statistics for the created archive')
         subparser.add_argument('--list', dest='output_list', action='store_true',
                                help='output verbose list of items (files, dirs, ...)')
-        subparser.add_argument('--filter', dest='output_filter', metavar='STATUSCHARS',
-                               help='only display items with the given status characters')
+        subparser.add_argument('--filter', metavar='STATUSCHARS', dest='output_filter',
+                               help='only display items with the given status characters (see description)')
         subparser.add_argument('--json', action='store_true',
                                help='output stats as JSON. Implies ``--stats``.')
         subparser.add_argument('--no-cache-sync', dest='no_cache_sync', action='store_true',
@@ -2873,11 +2871,10 @@ class Archiver:
         archive_group = subparser.add_argument_group('Archive options')
         archive_group.add_argument('--comment', dest='comment', metavar='COMMENT', default='',
                                    help='add a comment text to the archive')
-        archive_group.add_argument('--timestamp', dest='timestamp',
+        archive_group.add_argument('--timestamp', metavar='TIMESTAMP', dest='timestamp',
                                    type=timestamp, default=None,
-                                   metavar='TIMESTAMP',
                                    help='manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). '
-                                        'alternatively, give a reference file/directory.')
+                                        'Alternatively, give a reference file/directory.')
         archive_group.add_argument('-c', '--checkpoint-interval', metavar='SECONDS', dest='checkpoint_interval',
                                    type=int, default=1800,
                                    help='write checkpoint every SECONDS seconds (Default: 1800)')
@@ -3104,7 +3101,7 @@ class Archiver:
         subparser.set_defaults(func=self.do_list)
         subparser.add_argument('--short', dest='short', action='store_true',
                                help='only print file/directory names, nothing else')
-        subparser.add_argument('--format', '--list-format', dest='format', type=str, metavar='FORMAT',
+        subparser.add_argument('--format', '--list-format', metavar='FORMAT', dest='format',
                                help='specify format for file listing '
                                     '(default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")')
         subparser.add_argument('--json', action='store_true',
@@ -3287,7 +3284,7 @@ class Archiver:
                                help='print statistics for the deleted archive')
         subparser.add_argument('--list', dest='output_list', action='store_true',
                                help='output verbose list of archives it keeps/prunes')
-        subparser.add_argument('--keep-within', dest='within', type=interval, metavar='INTERVAL',
+        subparser.add_argument('--keep-within', metavar='INTERVAL', dest='within', type=interval,
                                help='keep all archives within this time interval')
         subparser.add_argument('--keep-last', '--keep-secondly', dest='secondly', type=int, default=0,
                                help='number of secondly archives to keep')
@@ -3478,13 +3475,12 @@ class Archiver:
                                    help='write checkpoint every SECONDS seconds (Default: 1800)')
         archive_group.add_argument('--comment', dest='comment', metavar='COMMENT', default=None,
                                    help='add a comment text to the archive')
-        archive_group.add_argument('--timestamp', dest='timestamp',
+        archive_group.add_argument('--timestamp', metavar='TIMESTAMP', dest='timestamp',
                                    type=timestamp, default=None,
-                                   metavar='TIMESTAMP',
                                    help='manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). '
                                         'alternatively, give a reference file/directory.')
-        archive_group.add_argument('-C', '--compression', dest='compression',
-                                   type=CompressionSpec, default=CompressionSpec('lz4'), metavar='COMPRESSION',
+        archive_group.add_argument('-C', '--compression', metavar='COMPRESSION', dest='compression',
+                                   type=CompressionSpec, default=CompressionSpec('lz4'),
                                    help='select compression algorithm, see the output of the '
                                         '"borg help compression" command for details.')
         archive_group.add_argument('--recompress', dest='recompress', nargs='?', default='never', const='if-different',
@@ -3493,9 +3489,8 @@ class Archiver:
                                         'When `always`, chunks that are already compressed that way are not skipped, '
                                         'but compressed again. Only the algorithm is considered for `if-different`, '
                                         'not the compression level (if any).')
-        archive_group.add_argument('--chunker-params', dest='chunker_params',
+        archive_group.add_argument('--chunker-params', metavar='PARAMS', dest='chunker_params',
                                    type=ChunkerParams, default=CHUNKER_PARAMS,
-                                   metavar='PARAMS',
                                    help='specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, '
                                         'HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. '
                                         'default: %d,%d,%d,%d' % CHUNKER_PARAMS)