Better help texts and Sphinx reproduction of usage

- Group options
- Nicer list of options in Sphinx
- Deduplicate 'Common options'
  (including --help)

The latter is done by explicitly declaring --help in the common_parser,
which is then inherited by the sub-parsers; no change in observable
behaviour.

borg/archiver.py

@@ -1015,43 +1015,46 @@ class Archiver:
 
     def build_parser(self, args=None, prog=None):
         common_parser = argparse.ArgumentParser(add_help=False, prog=prog)
-        common_parser.add_argument('--critical', dest='log_level',
-                                   action='store_const', const='critical', default='warning',
-                                   help='work on log level CRITICAL')
-        common_parser.add_argument('--error', dest='log_level',
-                                   action='store_const', const='error', default='warning',
-                                   help='work on log level ERROR')
-        common_parser.add_argument('--warning', dest='log_level',
-                                   action='store_const', const='warning', default='warning',
-                                   help='work on log level WARNING (default)')
-        common_parser.add_argument('--info', '-v', '--verbose', dest='log_level',
-                                   action='store_const', const='info', default='warning',
-                                   help='work on log level INFO')
-        common_parser.add_argument('--debug', dest='log_level',
-                                   action='store_const', const='debug', default='warning',
-                                   help='work on log level DEBUG')
-        common_parser.add_argument('--lock-wait', dest='lock_wait', type=int, metavar='N', default=1,
-                                   help='wait for the lock, but max. N seconds (default: %(default)d).')
-        common_parser.add_argument('--show-version', dest='show_version', action='store_true', default=False,
-                                   help='show/log the borg version')
-        common_parser.add_argument('--show-rc', dest='show_rc', action='store_true', default=False,
-                                   help='show/log the return code (rc)')
-        common_parser.add_argument('--no-files-cache', dest='cache_files', action='store_false',
-                                   help='do not load/update the file metadata cache used to detect unchanged files')
-        common_parser.add_argument('--umask', dest='umask', type=lambda s: int(s, 8), default=UMASK_DEFAULT, metavar='M',
-                                   help='set umask to M (local and remote, default: %(default)04o)')
-        common_parser.add_argument('--remote-path', dest='remote_path', default='borg', metavar='PATH',
-                                   help='set remote path to executable (default: "%(default)s")')
+
+        common_group = common_parser.add_argument_group('Common options')
+        common_group.add_argument('-h', '--help', action='help', help='show this help message and exit')
+        common_group.add_argument('--critical', dest='log_level',
+                                  action='store_const', const='critical', default='warning',
+                                  help='work on log level CRITICAL')
+        common_group.add_argument('--error', dest='log_level',
+                                  action='store_const', const='error', default='warning',
+                                  help='work on log level ERROR')
+        common_group.add_argument('--warning', dest='log_level',
+                                  action='store_const', const='warning', default='warning',
+                                  help='work on log level WARNING (default)')
+        common_group.add_argument('--info', '-v', '--verbose', dest='log_level',
+                                  action='store_const', const='info', default='warning',
+                                  help='work on log level INFO')
+        common_group.add_argument('--debug', dest='log_level',
+                                  action='store_const', const='debug', default='warning',
+                                  help='enable debug output, work on log level DEBUG')
+        common_group.add_argument('--lock-wait', dest='lock_wait', type=int, metavar='N', default=1,
+                                  help='wait for the lock, but max. N seconds (default: %(default)d).')
+        common_group.add_argument('--show-version', dest='show_version', action='store_true', default=False,
+                                  help='show/log the borg version')
+        common_group.add_argument('--show-rc', dest='show_rc', action='store_true', default=False,
+                                  help='show/log the return code (rc)')
+        common_group.add_argument('--no-files-cache', dest='cache_files', action='store_false',
+                                  help='do not load/update the file metadata cache used to detect unchanged files')
+        common_group.add_argument('--umask', dest='umask', type=lambda s: int(s, 8), default=UMASK_DEFAULT, metavar='M',
+                                  help='set umask to M (local and remote, default: %(default)04o)')
+        common_group.add_argument('--remote-path', dest='remote_path', default='borg', metavar='PATH',
+                                  help='set remote path to executable (default: "%(default)s")')
 
         parser = argparse.ArgumentParser(prog=prog, description='Borg - Deduplicated Backups')
         parser.add_argument('-V', '--version', action='version', version='%(prog)s ' + __version__,
-                                   help='show version number and exit')
+                            help='show version number and exit')
         subparsers = parser.add_subparsers(title='required arguments', metavar='<command>')
 
         serve_epilog = textwrap.dedent("""
         This command starts a repository server process. This command is usually not used manually.
         """)
-        subparser = subparsers.add_parser('serve', parents=[common_parser],
+        subparser = subparsers.add_parser('serve', parents=[common_parser], add_help=False,
                                           description=self.do_serve.__doc__, epilog=serve_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
                                           help='start repository server process')
@@ -1063,7 +1066,7 @@ class Archiver:
         directory containing the deduplicated data from zero or more archives.
         Encryption can be enabled at repository init time.
         """)
-        subparser = subparsers.add_parser('init', parents=[common_parser],
+        subparser = subparsers.add_parser('init', parents=[common_parser], add_help=False,
                                           description=self.do_init.__doc__, epilog=init_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
                                           help='initialize empty repository')
@@ -1111,7 +1114,7 @@ class Archiver:
         - The archive checks can be time consuming, they can be skipped using the
           --repository-only option.
         """)
-        subparser = subparsers.add_parser('check', parents=[common_parser],
+        subparser = subparsers.add_parser('check', parents=[common_parser], add_help=False,
                                           description=self.do_check.__doc__,
                                           epilog=check_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1142,7 +1145,7 @@ class Archiver:
         The key files used for repository encryption are optionally passphrase
         protected. This command can be used to change this passphrase.
         """)
-        subparser = subparsers.add_parser('change-passphrase', parents=[common_parser],
+        subparser = subparsers.add_parser('change-passphrase', parents=[common_parser], add_help=False,
                                           description=self.do_change_passphrase.__doc__,
                                           epilog=change_passphrase_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1169,7 +1172,7 @@ class Archiver:
         But please note: the secrets will always stay the same and they could always
         be derived from your (old) passphrase-mode passphrase.
         """)
-        subparser = subparsers.add_parser('migrate-to-repokey', parents=[common_parser],
+        subparser = subparsers.add_parser('migrate-to-repokey', parents=[common_parser], add_help=False,
                                           description=self.do_migrate_to_repokey.__doc__,
                                           epilog=migrate_to_repokey_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1192,78 +1195,88 @@ class Archiver:
         See the output of the "borg help patterns" command for more help on exclude patterns.
         """)
 
-        subparser = subparsers.add_parser('create', parents=[common_parser],
+        subparser = subparsers.add_parser('create', parents=[common_parser], add_help=False,
                                           description=self.do_create.__doc__,
                                           epilog=create_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
                                           help='create backup')
         subparser.set_defaults(func=self.do_create)
-        subparser.add_argument('--comment', dest='comment', metavar='COMMENT', default='',
-                               help='add a comment text to the archive')
+
+        subparser.add_argument('-n', '--dry-run', dest='dry_run',
+                               action='store_true', default=False,
+                               help='do not create a backup archive')
+
         subparser.add_argument('-s', '--stats', dest='stats',
                                action='store_true', default=False,
                                help='print statistics for the created archive')
         subparser.add_argument('-p', '--progress', dest='progress',
                                action='store_true', default=False,
-                               help="""show progress display while creating the archive, showing Original,
-                               Compressed and Deduplicated sizes, followed by the Number of files seen
-                               and the path being processed, default: %(default)s""")
+                               help='show progress display while creating the archive, showing Original, '
+                                    'Compressed and Deduplicated sizes, followed by the Number of files seen '
+                                    'and the path being processed, default: %(default)s')
         subparser.add_argument('--list', dest='output_list',
                                action='store_true', default=False,
                                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('-e', '--exclude', dest='excludes',
-                               type=parse_pattern, action='append',
-                               metavar="PATTERN", help='exclude paths matching PATTERN')
-        subparser.add_argument('--exclude-from', dest='exclude_files',
-                               type=argparse.FileType('r'), action='append',
-                               metavar='EXCLUDEFILE', help='read exclude patterns from EXCLUDEFILE, one per line')
-        subparser.add_argument('--exclude-caches', dest='exclude_caches',
-                               action='store_true', default=False,
-                               help='exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)')
-        subparser.add_argument('--exclude-if-present', dest='exclude_if_present',
-                               metavar='FILENAME', action='append', type=str,
-                               help='exclude directories that contain the specified file')
-        subparser.add_argument('--keep-tag-files', dest='keep_tag_files',
-                               action='store_true', default=False,
-                               help='keep tag files of excluded caches/directories')
-        subparser.add_argument('-c', '--checkpoint-interval', dest='checkpoint_interval',
-                               type=int, default=300, metavar='SECONDS',
-                               help='write checkpoint every SECONDS seconds (Default: 300)')
-        subparser.add_argument('-x', '--one-file-system', dest='one_file_system',
-                               action='store_true', default=False,
-                               help='stay in same file system, do not cross mount points')
-        subparser.add_argument('--numeric-owner', dest='numeric_owner',
-                               action='store_true', default=False,
-                               help='only store numeric user and group identifiers')
-        subparser.add_argument('--timestamp', dest='timestamp',
-                               type=timestamp, default=None,
-                               metavar='yyyy-mm-ddThh:mm:ss',
-                               help='manually specify the archive creation date/time (UTC). '
-                                    'alternatively, give a reference file/directory.')
-        subparser.add_argument('--chunker-params', dest='chunker_params',
-                               type=ChunkerParams, default=CHUNKER_PARAMS,
-                               metavar='CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE',
-                               help='specify the chunker parameters. default: %d,%d,%d,%d' % CHUNKER_PARAMS)
-        subparser.add_argument('--ignore-inode', dest='ignore_inode',
-                               action='store_true', default=False,
-                               help='ignore inode data in the file metadata cache used to detect unchanged files.')
-        subparser.add_argument('-C', '--compression', dest='compression',
-                               type=CompressionSpec, default=dict(name='none'), metavar='COMPRESSION',
-                               help='select compression algorithm (and level): '
-                                    'none == no compression (default), '
-                                    'lz4 == lz4, '
-                                    'zlib == zlib (default level 6), '
-                                    'zlib,0 .. zlib,9 == zlib (with level 0..9), '
-                                    'lzma == lzma (default level 6), '
-                                    'lzma,0 .. lzma,9 == lzma (with level 0..9).')
-        subparser.add_argument('--read-special', dest='read_special',
-                               action='store_true', default=False,
-                               help='open and read special files as if they were regular files')
-        subparser.add_argument('-n', '--dry-run', dest='dry_run',
-                               action='store_true', default=False,
-                               help='do not create a backup archive')
+
+        exclude_group = subparser.add_argument_group('Exclusion options')
+        exclude_group.add_argument('-e', '--exclude', dest='excludes',
+                                   type=parse_pattern, action='append',
+                                   metavar="PATTERN", help='exclude paths matching PATTERN')
+        exclude_group.add_argument('--exclude-from', dest='exclude_files',
+                                   type=argparse.FileType('r'), action='append',
+                                   metavar='EXCLUDEFILE', help='read exclude patterns from EXCLUDEFILE, one per line')
+        exclude_group.add_argument('--exclude-caches', dest='exclude_caches',
+                                   action='store_true', default=False,
+                                   help='exclude directories that contain a CACHEDIR.TAG file ('
+                                        'http://www.brynosaurus.com/cachedir/spec.html)')
+        exclude_group.add_argument('--exclude-if-present', dest='exclude_if_present',
+                                   metavar='FILENAME', action='append', type=str,
+                                   help='exclude directories that contain the specified file')
+        exclude_group.add_argument('--keep-tag-files', dest='keep_tag_files',
+                                   action='store_true', default=False,
+                                   help='keep tag files of excluded caches/directories')
+
+        fs_group = subparser.add_argument_group('Filesystem options')
+        fs_group.add_argument('-x', '--one-file-system', dest='one_file_system',
+                              action='store_true', default=False,
+                              help='stay in same file system, do not cross mount points')
+        fs_group.add_argument('--numeric-owner', dest='numeric_owner',
+                              action='store_true', default=False,
+                              help='only store numeric user and group identifiers')
+        fs_group.add_argument('--ignore-inode', dest='ignore_inode',
+                              action='store_true', default=False,
+                              help='ignore inode data in the file metadata cache used to detect unchanged files.')
+        fs_group.add_argument('--read-special', dest='read_special',
+                              action='store_true', default=False,
+                              help='open and read special files as if they were regular files')
+
+        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',
+                                   type=timestamp, default=None,
+                                   metavar='yyyy-mm-ddThh:mm:ss',
+                                   help='manually specify the archive creation date/time (UTC). '
+                                        'alternatively, give a reference file/directory.')
+        archive_group.add_argument('-c', '--checkpoint-interval', dest='checkpoint_interval',
+                                   type=int, default=300, metavar='SECONDS',
+                                   help='write checkpoint every SECONDS seconds (Default: 300)')
+        archive_group.add_argument('--chunker-params', dest='chunker_params',
+                                   type=ChunkerParams, default=CHUNKER_PARAMS,
+                                   metavar='CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE',
+                                   help='specify the chunker parameters. default: %d,%d,%d,%d' % CHUNKER_PARAMS)
+        archive_group.add_argument('-C', '--compression', dest='compression',
+                                   type=CompressionSpec, default=dict(name='none'), metavar='COMPRESSION',
+                                   help='select compression algorithm (and level):\n'
+                                        'none == no compression (default),\n'
+                                        'lz4 == lz4,\n'
+                                        'zlib == zlib (default level 6),\n'
+                                        'zlib,0 .. zlib,9 == zlib (with level 0..9),\n'
+                                        'lzma == lzma (default level 6),\n'
+                                        'lzma,0 .. lzma,9 == lzma (with level 0..9).')
+
         subparser.add_argument('location', metavar='ARCHIVE',
                                type=location_validator(archive=True),
                                help='name of archive to create (must be also a valid directory name)')
@@ -1278,7 +1291,7 @@ class Archiver:
 
         See the output of the "borg help patterns" command for more help on exclude patterns.
         """)
-        subparser = subparsers.add_parser('extract', parents=[common_parser],
+        subparser = subparsers.add_parser('extract', parents=[common_parser], add_help=False,
                                           description=self.do_extract.__doc__,
                                           epilog=extract_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1331,7 +1344,7 @@ class Archiver:
 
             See the output of the "borg help patterns" command for more help on exclude patterns.
             """)
-        subparser = subparsers.add_parser('diff', parents=[common_parser],
+        subparser = subparsers.add_parser('diff', parents=[common_parser], add_help=False,
                                           description=self.do_diff.__doc__,
                                           epilog=diff_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1363,8 +1376,10 @@ class Archiver:
 
         rename_epilog = textwrap.dedent("""
         This command renames an archive in the repository.
+
+        This results in a different archive ID.
         """)
-        subparser = subparsers.add_parser('rename', parents=[common_parser],
+        subparser = subparsers.add_parser('rename', parents=[common_parser], add_help=False,
                                           description=self.do_rename.__doc__,
                                           epilog=rename_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1379,8 +1394,10 @@ class Archiver:
 
         comment_epilog = textwrap.dedent("""
         This command sets the archive comment.
+
+        This results in a different archive ID.
         """)
-        subparser = subparsers.add_parser('comment', parents=[common_parser],
+        subparser = subparsers.add_parser('comment', parents=[common_parser], add_help=False,
                                           description=self.do_comment.__doc__,
                                           epilog=comment_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1397,7 +1414,7 @@ class Archiver:
         Disk space is reclaimed accordingly. If you delete the complete repository, the
         local cache for it (if any) is also deleted.
         """)
-        subparser = subparsers.add_parser('delete', parents=[common_parser],
+        subparser = subparsers.add_parser('delete', parents=[common_parser], add_help=False,
                                           description=self.do_delete.__doc__,
                                           epilog=delete_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1427,7 +1444,7 @@ class Archiver:
         The following keys are available for --format when listing files:
 
         """) + ItemFormatter.keys_help()
-        subparser = subparsers.add_parser('list', parents=[common_parser],
+        subparser = subparsers.add_parser('list', parents=[common_parser], add_help=False,
                                           description=self.do_list.__doc__,
                                           epilog=list_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1466,7 +1483,7 @@ class Archiver:
         To allow a regular user to use fstab entries, add the ``user`` option:
         ``/path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0``
         """)
-        subparser = subparsers.add_parser('mount', parents=[common_parser],
+        subparser = subparsers.add_parser('mount', parents=[common_parser], add_help=False,
                                           description=self.do_mount.__doc__,
                                           epilog=mount_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1485,7 +1502,7 @@ class Archiver:
         info_epilog = textwrap.dedent("""
         This command displays some detailed information about the specified archive.
         """)
-        subparser = subparsers.add_parser('info', parents=[common_parser],
+        subparser = subparsers.add_parser('info', parents=[common_parser], add_help=False,
                                           description=self.do_info.__doc__,
                                           epilog=info_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1500,7 +1517,7 @@ class Archiver:
         Please use carefully and only while no borg process (on any machine) is
         trying to access the Cache or the Repository.
         """)
-        subparser = subparsers.add_parser('break-lock', parents=[common_parser],
+        subparser = subparsers.add_parser('break-lock', parents=[common_parser], add_help=False,
                                           description=self.do_break_lock.__doc__,
                                           epilog=break_lock_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1534,7 +1551,7 @@ class Archiver:
         specified by the rules.
         Otherwise, *all* archives in the repository are candidates for deletion!
         """)
-        subparser = subparsers.add_parser('prune', parents=[common_parser],
+        subparser = subparsers.add_parser('prune', parents=[common_parser], add_help=False,
                                           description=self.do_prune.__doc__,
                                           epilog=prune_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1608,7 +1625,7 @@ class Archiver:
         to previous versions. This can PERMANENTLY DAMAGE YOUR
         REPOSITORY!  Attic CAN NOT READ BORG REPOSITORIES, as the
         magic strings have changed. You have been warned.""")
-        subparser = subparsers.add_parser('upgrade', parents=[common_parser],
+        subparser = subparsers.add_parser('upgrade', parents=[common_parser], add_help=False,
                                           description=self.do_upgrade.__doc__,
                                           epilog=upgrade_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1628,7 +1645,7 @@ class Archiver:
                                type=location_validator(archive=False),
                                help='path to the repository to be upgraded')
 
-        subparser = subparsers.add_parser('help', parents=[common_parser],
+        subparser = subparsers.add_parser('help', parents=[common_parser], add_help=False,
                                           description='Extra help')
         subparser.add_argument('--epilog-only', dest='epilog_only',
                                action='store_true', default=False)
@@ -1641,7 +1658,7 @@ class Archiver:
         debug_dump_archive_items_epilog = textwrap.dedent("""
         This command dumps raw (but decrypted and decompressed) archive items (only metadata) to files.
         """)
-        subparser = subparsers.add_parser('debug-dump-archive-items', parents=[common_parser],
+        subparser = subparsers.add_parser('debug-dump-archive-items', parents=[common_parser], add_help=False,
                                           description=self.do_debug_dump_archive_items.__doc__,
                                           epilog=debug_dump_archive_items_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1654,7 +1671,7 @@ class Archiver:
         debug_get_obj_epilog = textwrap.dedent("""
         This command gets an object from the repository.
         """)
-        subparser = subparsers.add_parser('debug-get-obj', parents=[common_parser],
+        subparser = subparsers.add_parser('debug-get-obj', parents=[common_parser], add_help=False,
                                           description=self.do_debug_get_obj.__doc__,
                                           epilog=debug_get_obj_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1671,7 +1688,7 @@ class Archiver:
         debug_put_obj_epilog = textwrap.dedent("""
         This command puts objects into the repository.
         """)
-        subparser = subparsers.add_parser('debug-put-obj', parents=[common_parser],
+        subparser = subparsers.add_parser('debug-put-obj', parents=[common_parser], add_help=False,
                                           description=self.do_debug_put_obj.__doc__,
                                           epilog=debug_put_obj_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -1686,7 +1703,7 @@ class Archiver:
         debug_delete_obj_epilog = textwrap.dedent("""
         This command deletes objects from the repository.
         """)
-        subparser = subparsers.add_parser('debug-delete-obj', parents=[common_parser],
+        subparser = subparsers.add_parser('debug-delete-obj', parents=[common_parser], add_help=False,
                                           description=self.do_debug_delete_obj.__doc__,
                                           epilog=debug_delete_obj_epilog,
                                           formatter_class=argparse.RawDescriptionHelpFormatter,

docs/borg_theme/css/borg.css

@@ -16,3 +16,7 @@
 .wy-side-nav-search > div.version {
     color: rgba(255, 255, 255, 0.5);
 }
+
+#usage dt code {
+    font-weight: normal;
+}

docs/usage.rst

@@ -191,6 +191,12 @@ For more information about that, see: https://xkcd.com/1179/
 Unless otherwise noted, we display local date and time.
 Internally, we store and process date and time as UTC.
 
+Common options
+~~~~~~~~~~~~~~
+
+All |project_name| commands share these options:
+
+.. include:: usage/common-options.rst.inc
 
 .. include:: usage/init.rst.inc
 
@@ -327,8 +333,11 @@ Examples
     # Restore a raw device (must not be active/in use/mounted at that time)
     $ borg extract --stdout /mnt/backup::my-sdx | dd of=/dev/sdx bs=10M
 
-Note: currently, extract always writes into the current working directory ("."),
-      so make sure you ``cd`` to the right place before calling ``borg extract``.
+
+.. Note::
+
+    Currently, extract always writes into the current working directory ("."),
+    so make sure you ``cd`` to the right place before calling ``borg extract``.
 
 .. include:: usage/check.rst.inc
 

docs/usage/break-lock.rst.inc

@@ -4,32 +4,15 @@ borg break-lock
 ---------------
 ::
 
-    usage: borg break-lock [-h] [--critical] [--error] [--warning] [--info]
-                           [--debug] [--lock-wait N] [--show-version] [--show-rc]
-                           [--no-files-cache] [--umask M] [--remote-path PATH]
-                           REPOSITORY
-    
-    Break the repository lock (e.g. in case it was left by a dead borg.
-    
-    positional arguments:
-      REPOSITORY            repository for which to break the locks
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg break-lock <options> REPOSITORY
+
+positional arguments
+    REPOSITORY
+        repository for which to break the locks
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/change-passphrase.rst.inc

@@ -4,33 +4,15 @@ borg change-passphrase
 ----------------------
 ::
 
-    usage: borg change-passphrase [-h] [--critical] [--error] [--warning] [--info]
-                                  [--debug] [--lock-wait N] [--show-version]
-                                  [--show-rc] [--no-files-cache] [--umask M]
-                                  [--remote-path PATH]
-                                  [REPOSITORY]
-    
-    Change repository key file passphrase
-    
-    positional arguments:
-      REPOSITORY
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg change-passphrase <options> REPOSITORY
+
+positional arguments
+    REPOSITORY
+
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/check.rst.inc

@@ -4,42 +4,29 @@ borg check
 ----------
 ::
 
-    usage: borg check [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                      [--lock-wait N] [--show-version] [--show-rc]
-                      [--no-files-cache] [--umask M] [--remote-path PATH]
-                      [--repository-only] [--archives-only] [--repair]
-                      [--save-space] [--last N] [-P PREFIX]
-                      [REPOSITORY_OR_ARCHIVE]
-    
-    Check repository consistency
-    
-    positional arguments:
-      REPOSITORY_OR_ARCHIVE
-                            repository or archive to check consistency of
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      --repository-only     only perform repository checks
-      --archives-only       only perform archives checks
-      --repair              attempt to repair any inconsistencies found
-      --save-space          work slower, but using less space
-      --last N              only check last N archives (Default: all)
-      -P PREFIX, --prefix PREFIX
-                            only consider archive names starting with this prefix
-    
+    borg check <options> REPOSITORY_OR_ARCHIVE
+
+positional arguments
+    REPOSITORY_OR_ARCHIVE
+        repository or archive to check consistency of
+
+optional arguments
+    ``--repository-only``
+        | only perform repository checks
+    ``--archives-only``
+        | only perform archives checks
+    ``--repair``
+        | attempt to repair any inconsistencies found
+    ``--save-space``
+        | work slower, but using less space
+    ``--last N``
+        | only check last N archives (Default: all)
+    ``-P``, ``--prefix``
+        | only consider archive names starting with this prefix
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/comment.rst.inc

@@ -4,34 +4,20 @@ borg comment
 ------------
 ::
 
-    usage: borg comment [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                        [--lock-wait N] [--show-version] [--show-rc]
-                        [--no-files-cache] [--umask M] [--remote-path PATH]
-                        ARCHIVE COMMENT
-    
-    Set the archive comment
-    
-    positional arguments:
-      ARCHIVE               archive to modify
-      COMMENT               the new archive comment
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg comment <options> ARCHIVE COMMENT
+
+positional arguments
+    ARCHIVE
+        archive to modify
+    COMMENT
+        the new archive comment
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 
 This command sets the archive comment.
+
+This results in a different archive ID.

docs/usage/common-options.rst.inc

@@ -0,0 +1,24 @@
+    ``-h``, ``--help``
+        | show this help message and exit
+    ``--critical``
+        | work on log level CRITICAL
+    ``--error``
+        | work on log level ERROR
+    ``--warning``
+        | work on log level WARNING (default)
+    ``--info``, ``-v``, ``--verbose``
+        | work on log level INFO
+    ``--debug``
+        | enable debug output, work on log level DEBUG
+    ``--lock-wait N``
+        | wait for the lock, but max. N seconds (default: 1).
+    ``--show-version``
+        | show/log the borg version
+    ``--show-rc``
+        | show/log the return code (rc)
+    ``--no-files-cache``
+        | do not load/update the file metadata cache used to detect unchanged files
+    ``--umask M``
+        | set umask to M (local and remote, default: 0077)
+    ``--remote-path PATH``
+        | set remote path to executable (default: "borg")

docs/usage/create.rst.inc

@@ -4,80 +4,69 @@ borg create
 -----------
 ::
 
-    usage: borg create [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                       [--lock-wait N] [--show-version] [--show-rc]
-                       [--no-files-cache] [--umask M] [--remote-path PATH]
-                       [--comment COMMENT] [-s] [-p] [--list]
-                       [--filter STATUSCHARS] [-e PATTERN]
-                       [--exclude-from EXCLUDEFILE] [--exclude-caches]
-                       [--exclude-if-present FILENAME] [--keep-tag-files]
-                       [-c SECONDS] [-x] [--numeric-owner]
-                       [--timestamp yyyy-mm-ddThh:mm:ss]
-                       [--chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE]
-                       [--ignore-inode] [-C COMPRESSION] [--read-special] [-n]
-                       ARCHIVE PATH [PATH ...]
-    
-    Create new archive
-    
-    positional arguments:
-      ARCHIVE               name of archive to create (must be also a valid
-                            directory name)
-      PATH                  paths to archive
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      --comment COMMENT     add a comment text to the archive
-      -s, --stats           print statistics for the created archive
-      -p, --progress        show progress display while creating the archive,
-                            showing Original, Compressed and Deduplicated sizes,
-                            followed by the Number of files seen and the path
-                            being processed, default: False
-      --list                output verbose list of items (files, dirs, ...)
-      --filter STATUSCHARS  only display items with the given status characters
-      -e PATTERN, --exclude PATTERN
-                            exclude paths matching PATTERN
-      --exclude-from EXCLUDEFILE
-                            read exclude patterns from EXCLUDEFILE, one per line
-      --exclude-caches      exclude directories that contain a CACHEDIR.TAG file
-                            (http://www.brynosaurus.com/cachedir/spec.html)
-      --exclude-if-present FILENAME
-                            exclude directories that contain the specified file
-      --keep-tag-files      keep tag files of excluded caches/directories
-      -c SECONDS, --checkpoint-interval SECONDS
-                            write checkpoint every SECONDS seconds (Default: 300)
-      -x, --one-file-system
-                            stay in same file system, do not cross mount points
-      --numeric-owner       only store numeric user and group identifiers
-      --timestamp yyyy-mm-ddThh:mm:ss
-                            manually specify the archive creation date/time (UTC).
-                            alternatively, give a reference file/directory.
-      --chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE
-                            specify the chunker parameters. default: 19,23,21,4095
-      --ignore-inode        ignore inode data in the file metadata cache used to
-                            detect unchanged files.
-      -C COMPRESSION, --compression COMPRESSION
-                            select compression algorithm (and level): none == no
-                            compression (default), lz4 == lz4, zlib == zlib
-                            (default level 6), zlib,0 .. zlib,9 == zlib (with
-                            level 0..9), lzma == lzma (default level 6), lzma,0 ..
-                            lzma,9 == lzma (with level 0..9).
-      --read-special        open and read special files as if they were regular
-                            files
-      -n, --dry-run         do not create a backup archive
-    
+    borg create <options> ARCHIVE PATH
+
+positional arguments
+    ARCHIVE
+        name of archive to create (must be also a valid directory name)
+    PATH
+        paths to archive
+
+optional arguments
+    ``-n``, ``--dry-run``
+        | do not create a backup archive
+    ``-s``, ``--stats``
+        | print statistics for the created archive
+    ``-p``, ``--progress``
+        | show progress display while creating the archive, showing Original, Compressed and Deduplicated sizes, followed by the Number of files seen and the path being processed, default: False
+    ``--list``
+        | output verbose list of items (files, dirs, ...)
+    ``--filter STATUSCHARS``
+        | only display items with the given status characters
+
+`Common options`_
+    |
+
+Exclusion options
+    ``-e PATTERN``, ``--exclude PATTERN``
+        | exclude paths matching PATTERN
+    ``--exclude-from EXCLUDEFILE``
+        | read exclude patterns from EXCLUDEFILE, one per line
+    ``--exclude-caches``
+        | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
+    ``--exclude-if-present FILENAME``
+        | exclude directories that contain the specified file
+    ``--keep-tag-files``
+        | keep tag files of excluded caches/directories
+
+Filesystem options
+    ``-x``, ``--one-file-system``
+        | stay in same file system, do not cross mount points
+    ``--numeric-owner``
+        | only store numeric user and group identifiers
+    ``--ignore-inode``
+        | ignore inode data in the file metadata cache used to detect unchanged files.
+    ``--read-special``
+        | open and read special files as if they were regular files
+
+Archive options
+    ``--comment COMMENT``
+        | add a comment text to the archive
+    ``--timestamp yyyy-mm-ddThh:mm:ss``
+        | manually specify the archive creation date/time (UTC). alternatively, give a reference file/directory.
+    ``-c SECONDS``, ``--checkpoint-interval SECONDS``
+        | write checkpoint every SECONDS seconds (Default: 300)
+    ``--chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE``
+        | specify the chunker parameters. default: 19,23,21,4095
+    ``-C COMPRESSION``, ``--compression COMPRESSION``
+        | select compression algorithm (and level):
+        | none == no compression (default),
+        | lz4 == lz4,
+        | zlib == zlib (default level 6),
+        | zlib,0 .. zlib,9 == zlib (with level 0..9),
+        | lzma == lzma (default level 6),
+        | lzma,0 .. lzma,9 == lzma (with level 0..9).
+
 Description
 ~~~~~~~~~~~
 

docs/usage/debug-delete-obj.rst.inc

@@ -4,34 +4,17 @@ borg debug-delete-obj
 ---------------------
 ::
 
-    usage: borg debug-delete-obj [-h] [--critical] [--error] [--warning] [--info]
-                                 [--debug] [--lock-wait N] [--show-version]
-                                 [--show-rc] [--no-files-cache] [--umask M]
-                                 [--remote-path PATH]
-                                 [REPOSITORY] IDs [IDs ...]
-    
-    delete the objects with the given IDs from the repo
-    
-    positional arguments:
-      REPOSITORY            repository to use
-      IDs                   hex object ID(s) to delete from the repo
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg debug-delete-obj <options> REPOSITORY IDs
+
+positional arguments
+    REPOSITORY
+        repository to use
+    IDs
+        hex object ID(s) to delete from the repo
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/debug-dump-archive-items.rst.inc

@@ -4,34 +4,15 @@ borg debug-dump-archive-items
 -----------------------------
 ::
 
-    usage: borg debug-dump-archive-items [-h] [--critical] [--error] [--warning]
-                                         [--info] [--debug] [--lock-wait N]
-                                         [--show-version] [--show-rc]
-                                         [--no-files-cache] [--umask M]
-                                         [--remote-path PATH]
-                                         ARCHIVE
-    
-    dump (decrypted, decompressed) archive items metadata (not: data)
-    
-    positional arguments:
-      ARCHIVE               archive to dump
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg debug-dump-archive-items <options> ARCHIVE
+
+positional arguments
+    ARCHIVE
+        archive to dump
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/debug-get-obj.rst.inc

@@ -4,35 +4,19 @@ borg debug-get-obj
 ------------------
 ::
 
-    usage: borg debug-get-obj [-h] [--critical] [--error] [--warning] [--info]
-                              [--debug] [--lock-wait N] [--show-version]
-                              [--show-rc] [--no-files-cache] [--umask M]
-                              [--remote-path PATH]
-                              [REPOSITORY] ID PATH
-    
-    get object contents from the repository and write it into file
-    
-    positional arguments:
-      REPOSITORY            repository to use
-      ID                    hex object ID to get from the repo
-      PATH                  file to write object data into
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg debug-get-obj <options> REPOSITORY ID PATH
+
+positional arguments
+    REPOSITORY
+        repository to use
+    ID
+        hex object ID to get from the repo
+    PATH
+        file to write object data into
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/debug-put-obj.rst.inc

@@ -4,34 +4,17 @@ borg debug-put-obj
 ------------------
 ::
 
-    usage: borg debug-put-obj [-h] [--critical] [--error] [--warning] [--info]
-                              [--debug] [--lock-wait N] [--show-version]
-                              [--show-rc] [--no-files-cache] [--umask M]
-                              [--remote-path PATH]
-                              [REPOSITORY] PATH [PATH ...]
-    
-    put file(s) contents into the repository
-    
-    positional arguments:
-      REPOSITORY            repository to use
-      PATH                  file(s) to read and create object(s) from
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg debug-put-obj <options> REPOSITORY PATH
+
+positional arguments
+    REPOSITORY
+        repository to use
+    PATH
+        file(s) to read and create object(s) from
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/delete.rst.inc

@@ -4,37 +4,25 @@ borg delete
 -----------
 ::
 
-    usage: borg delete [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                       [--lock-wait N] [--show-version] [--show-rc]
-                       [--no-files-cache] [--umask M] [--remote-path PATH] [-p]
-                       [-s] [-c] [--save-space]
-                       [TARGET]
-    
-    Delete an existing repository or archive
-    
-    positional arguments:
-      TARGET                archive or repository to delete
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      -p, --progress        show progress display while deleting a single archive
-      -s, --stats           print statistics for the deleted archive
-      -c, --cache-only      delete only the local cache for the given repository
-      --save-space          work slower, but using less space
-    
+    borg delete <options> TARGET
+
+positional arguments
+    TARGET
+        archive or repository to delete
+
+optional arguments
+    ``-p``, ``--progress``
+        | show progress display while deleting a single archive
+    ``-s``, ``--stats``
+        | print statistics for the deleted archive
+    ``-c``, ``--cache-only``
+        | delete only the local cache for the given repository
+    ``--save-space``
+        | work slower, but using less space
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/diff.rst.inc

@@ -4,45 +4,31 @@ borg diff
 ---------
 ::
 
-    usage: borg diff [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                     [--lock-wait N] [--show-version] [--show-rc]
-                     [--no-files-cache] [--umask M] [--remote-path PATH]
-                     [-e PATTERN] [--exclude-from EXCLUDEFILE] [--numeric-owner]
-                     [--same-chunker-params] [--sort]
-                     ARCHIVE1 ARCHIVE2 [PATH [PATH ...]]
-    
-    Diff contents of two archives
-    
-    positional arguments:
-      ARCHIVE1              archive
-      ARCHIVE2              archive to compare with ARCHIVE1 (no repository
-                            location)
-      PATH                  paths to compare; patterns are supported
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      -e PATTERN, --exclude PATTERN
-                            exclude paths matching PATTERN
-      --exclude-from EXCLUDEFILE
-                            read exclude patterns from EXCLUDEFILE, one per line
-      --numeric-owner       only consider numeric user and group identifiers
-      --same-chunker-params
-                            Override check of chunker parameters.
-      --sort                Sort the output lines by file path.
-    
+    borg diff <options> ARCHIVE1 ARCHIVE2 PATH
+
+positional arguments
+    ARCHIVE1
+        archive
+    ARCHIVE2
+        archive to compare with ARCHIVE1 (no repository location)
+    PATH
+        paths to compare; patterns are supported
+
+optional arguments
+    ``-e PATTERN``, ``--exclude PATTERN``
+        | exclude paths matching PATTERN
+    ``--exclude-from EXCLUDEFILE``
+        | read exclude patterns from EXCLUDEFILE, one per line
+    ``--numeric-owner``
+        | only consider numeric user and group identifiers
+    ``--same-chunker-params``
+        | Override check of chunker parameters.
+    ``--sort``
+        | Sort the output lines by file path.
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/extract.rst.inc

@@ -4,50 +4,35 @@ borg extract
 ------------
 ::
 
-    usage: borg extract [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                        [--lock-wait N] [--show-version] [--show-rc]
-                        [--no-files-cache] [--umask M] [--remote-path PATH]
-                        [--list] [-n] [-e PATTERN] [--exclude-from EXCLUDEFILE]
-                        [--numeric-owner] [--strip-components NUMBER] [--stdout]
-                        [--sparse]
-                        ARCHIVE [PATH [PATH ...]]
-    
-    Extract archive contents
-    
-    positional arguments:
-      ARCHIVE               archive to extract
-      PATH                  paths to extract; patterns are supported
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      --list                output verbose list of items (files, dirs, ...)
-      -n, --dry-run         do not actually change any files
-      -e PATTERN, --exclude PATTERN
-                            exclude paths matching PATTERN
-      --exclude-from EXCLUDEFILE
-                            read exclude patterns from EXCLUDEFILE, one per line
-      --numeric-owner       only obey numeric user and group identifiers
-      --strip-components NUMBER
-                            Remove the specified number of leading path elements.
-                            Pathnames with fewer elements will be silently
-                            skipped.
-      --stdout              write all extracted data to stdout
-      --sparse              create holes in output sparse file from all-zero
-                            chunks
-    
+    borg extract <options> ARCHIVE PATH
+
+positional arguments
+    ARCHIVE
+        archive to extract
+    PATH
+        paths to extract; patterns are supported
+
+optional arguments
+    ``--list``
+        | output verbose list of items (files, dirs, ...)
+    ``-n``, ``--dry-run``
+        | do not actually change any files
+    ``-e PATTERN``, ``--exclude PATTERN``
+        | exclude paths matching PATTERN
+    ``--exclude-from EXCLUDEFILE``
+        | read exclude patterns from EXCLUDEFILE, one per line
+    ``--numeric-owner``
+        | only obey numeric user and group identifiers
+    ``--strip-components NUMBER``
+        | Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
+    ``--stdout``
+        | write all extracted data to stdout
+    ``--sparse``
+        | create holes in output sparse file from all-zero chunks
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/info.rst.inc

@@ -4,32 +4,15 @@ borg info
 ---------
 ::
 
-    usage: borg info [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                     [--lock-wait N] [--show-version] [--show-rc]
-                     [--no-files-cache] [--umask M] [--remote-path PATH]
-                     ARCHIVE
-    
-    Show archive details such as disk space used
-    
-    positional arguments:
-      ARCHIVE               archive to display information about
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg info <options> ARCHIVE
+
+positional arguments
+    ARCHIVE
+        archive to display information about
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/init.rst.inc

@@ -4,35 +4,19 @@ borg init
 ---------
 ::
 
-    usage: borg init [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                     [--lock-wait N] [--show-version] [--show-rc]
-                     [--no-files-cache] [--umask M] [--remote-path PATH]
-                     [-e {none,keyfile,repokey}]
-                     [REPOSITORY]
-    
-    Initialize an empty repository
-    
-    positional arguments:
-      REPOSITORY            repository to create
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      -e {none,keyfile,repokey}, --encryption {none,keyfile,repokey}
-                            select encryption key mode (default: "repokey")
-    
+    borg init <options> REPOSITORY
+
+positional arguments
+    REPOSITORY
+        repository to create
+
+optional arguments
+    ``-e``, ``--encryption``
+        | select encryption key mode (default: "repokey")
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/list.rst.inc

@@ -4,47 +4,30 @@ borg list
 ---------
 ::
 
-    usage: borg list [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                     [--lock-wait N] [--show-version] [--show-rc]
-                     [--no-files-cache] [--umask M] [--remote-path PATH] [--short]
-                     [--format FORMAT] [-P PREFIX] [-e PATTERN]
-                     [--exclude-from EXCLUDEFILE]
-                     [REPOSITORY_OR_ARCHIVE] [PATH [PATH ...]]
-    
-    List archive or repository contents
-    
-    positional arguments:
-      REPOSITORY_OR_ARCHIVE
-                            repository/archive to list contents of
-      PATH                  paths to list; patterns are supported
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      --short               only print file/directory names, nothing else
-      --format FORMAT, --list-format FORMAT
-                            specify format for file listing (default: "{mode}
-                            {user:6} {group:6} {size:8d} {isomtime}
-                            {path}{extra}{NL}")
-      -P PREFIX, --prefix PREFIX
-                            only consider archive names starting with this prefix
-      -e PATTERN, --exclude PATTERN
-                            exclude paths matching PATTERN
-      --exclude-from EXCLUDEFILE
-                            read exclude patterns from EXCLUDEFILE, one per line
-    
+    borg list <options> REPOSITORY_OR_ARCHIVE PATH
+
+positional arguments
+    REPOSITORY_OR_ARCHIVE
+        repository/archive to list contents of
+    PATH
+        paths to list; patterns are supported
+
+optional arguments
+    ``--short``
+        | only print file/directory names, nothing else
+    ``--format``, ``--list-format``
+        | specify format for file listing
+        |                                 (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")
+    ``-P``, ``--prefix``
+        | only consider archive names starting with this prefix
+    ``-e PATTERN``, ``--exclude PATTERN``
+        | exclude paths matching PATTERN
+    ``--exclude-from EXCLUDEFILE``
+        | read exclude patterns from EXCLUDEFILE, one per line
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/migrate-to-repokey.rst.inc

@@ -4,33 +4,15 @@ borg migrate-to-repokey
 -----------------------
 ::
 
-    usage: borg migrate-to-repokey [-h] [--critical] [--error] [--warning]
-                                   [--info] [--debug] [--lock-wait N]
-                                   [--show-version] [--show-rc] [--no-files-cache]
-                                   [--umask M] [--remote-path PATH]
-                                   [REPOSITORY]
-    
-    Migrate passphrase -> repokey
-    
-    positional arguments:
-      REPOSITORY
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg migrate-to-repokey <options> REPOSITORY
+
+positional arguments
+    REPOSITORY
+
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/mount.rst.inc

@@ -4,37 +4,23 @@ borg mount
 ----------
 ::
 
-    usage: borg mount [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                      [--lock-wait N] [--show-version] [--show-rc]
-                      [--no-files-cache] [--umask M] [--remote-path PATH] [-f]
-                      [-o OPTIONS]
-                      REPOSITORY_OR_ARCHIVE MOUNTPOINT
-    
-    Mount archive or an entire repository as a FUSE fileystem
-    
-    positional arguments:
-      REPOSITORY_OR_ARCHIVE
-                            repository/archive to mount
-      MOUNTPOINT            where to mount filesystem
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      -f, --foreground      stay in foreground, do not daemonize
-      -o OPTIONS            Extra mount options
-    
+    borg mount <options> REPOSITORY_OR_ARCHIVE MOUNTPOINT
+
+positional arguments
+    REPOSITORY_OR_ARCHIVE
+        repository/archive to mount
+    MOUNTPOINT
+        where to mount filesystem
+
+optional arguments
+    ``-f``, ``--foreground``
+        | stay in foreground, do not daemonize
+    ``-o``
+        | Extra mount options
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/prune.rst.inc

@@ -4,52 +4,39 @@ borg prune
 ----------
 ::
 
-    usage: borg prune [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                      [--lock-wait N] [--show-version] [--show-rc]
-                      [--no-files-cache] [--umask M] [--remote-path PATH] [-n]
-                      [-s] [--list] [--keep-within WITHIN] [-H HOURLY] [-d DAILY]
-                      [-w WEEKLY] [-m MONTHLY] [-y YEARLY] [-P PREFIX]
-                      [--save-space]
-                      [REPOSITORY]
-    
-    Prune repository archives according to specified rules
-    
-    positional arguments:
-      REPOSITORY            repository to prune
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      -n, --dry-run         do not change repository
-      -s, --stats           print statistics for the deleted archive
-      --list                output verbose list of archives it keeps/prunes
-      --keep-within WITHIN  keep all archives within this time interval
-      -H HOURLY, --keep-hourly HOURLY
-                            number of hourly archives to keep
-      -d DAILY, --keep-daily DAILY
-                            number of daily archives to keep
-      -w WEEKLY, --keep-weekly WEEKLY
-                            number of weekly archives to keep
-      -m MONTHLY, --keep-monthly MONTHLY
-                            number of monthly archives to keep
-      -y YEARLY, --keep-yearly YEARLY
-                            number of yearly archives to keep
-      -P PREFIX, --prefix PREFIX
-                            only consider archive names starting with this prefix
-      --save-space          work slower, but using less space
-    
+    borg prune <options> REPOSITORY
+
+positional arguments
+    REPOSITORY
+        repository to prune
+
+optional arguments
+    ``-n``, ``--dry-run``
+        | do not change repository
+    ``-s``, ``--stats``
+        | print statistics for the deleted archive
+    ``--list``
+        | output verbose list of archives it keeps/prunes
+    ``--keep-within WITHIN``
+        | keep all archives within this time interval
+    ``-H``, ``--keep-hourly``
+        | number of hourly archives to keep
+    ``-d``, ``--keep-daily``
+        | number of daily archives to keep
+    ``-w``, ``--keep-weekly``
+        | number of weekly archives to keep
+    ``-m``, ``--keep-monthly``
+        | number of monthly archives to keep
+    ``-y``, ``--keep-yearly``
+        | number of yearly archives to keep
+    ``-P``, ``--prefix``
+        | only consider archive names starting with this prefix
+    ``--save-space``
+        | work slower, but using less space
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/rename.rst.inc

@@ -4,34 +4,20 @@ borg rename
 -----------
 ::
 
-    usage: borg rename [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                       [--lock-wait N] [--show-version] [--show-rc]
-                       [--no-files-cache] [--umask M] [--remote-path PATH]
-                       ARCHIVE NEWNAME
-    
-    Rename an existing archive
-    
-    positional arguments:
-      ARCHIVE               archive to rename
-      NEWNAME               the new archive name to use
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg rename <options> ARCHIVE NEWNAME
+
+positional arguments
+    ARCHIVE
+        archive to rename
+    NEWNAME
+        the new archive name to use
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 
 This command renames an archive in the repository.
+
+This results in a different archive ID.

docs/usage/serve.rst.inc

@@ -4,32 +4,15 @@ borg serve
 ----------
 ::
 
-    usage: borg serve [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                      [--lock-wait N] [--show-version] [--show-rc]
-                      [--no-files-cache] [--umask M] [--remote-path PATH]
-                      [--restrict-to-path PATH]
-    
-    Start in server mode. This command is usually not used manually.
-            
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      --restrict-to-path PATH
-                            restrict repository access to PATH
-    
+    borg serve <options>
+
+optional arguments
+    ``--restrict-to-path PATH``
+        | restrict repository access to PATH
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

docs/usage/upgrade.rst.inc

@@ -4,37 +4,24 @@ borg upgrade
 ------------
 ::
 
-    usage: borg upgrade [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                        [--lock-wait N] [--show-version] [--show-rc]
-                        [--no-files-cache] [--umask M] [--remote-path PATH] [-p]
-                        [-n] [-i]
-                        [REPOSITORY]
-    
-    upgrade a repository from a previous version
-    
-    positional arguments:
-      REPOSITORY            path to the repository to be upgraded
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      -p, --progress        show progress display while upgrading the repository
-      -n, --dry-run         do not change repository
-      -i, --inplace         rewrite repository in place, with no chance of going
-                            back to older versions of the repository.
-    
+    borg upgrade <options> REPOSITORY
+
+positional arguments
+    REPOSITORY
+        path to the repository to be upgraded
+
+optional arguments
+    ``-p``, ``--progress``
+        | show progress display while upgrading the repository
+    ``-n``, ``--dry-run``
+        | do not change repository
+    ``-i``, ``--inplace``
+        | rewrite repository in place, with no chance of going back to older
+        |                                versions of the repository.
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 

setup.py

@@ -7,6 +7,8 @@ from glob import glob
 from distutils.command.build import build
 from distutils.core import Command
 
+import textwrap
+
 min_python = (3, 4)
 my_python = sys.version_info
 
@@ -168,12 +170,72 @@ class build_usage(Command):
                     params = {"command": command,
                               "underline": '-' * len('borg ' + command)}
                     doc.write(".. _borg_{command}:\n\n".format(**params))
-                    doc.write("borg {command}\n{underline}\n::\n\n".format(**params))
+                    doc.write("borg {command}\n{underline}\n::\n\n    borg {command}".format(**params))
+                    self.write_usage(parser, doc)
                     epilog = parser.epilog
                     parser.epilog = None
-                    doc.write(re.sub("^", "    ", parser.format_help(), flags=re.M))
-                    doc.write("\nDescription\n~~~~~~~~~~~\n")
+                    self.write_options(parser, doc)
+                    doc.write("\n\nDescription\n~~~~~~~~~~~\n")
                     doc.write(epilog)
+        common_options = [group for group in choices['create']._action_groups if group.title == 'Common options'][0]
+        with open('docs/usage/common-options.rst.inc', 'w') as doc:
+            self.write_options_group(common_options, doc, False)
+
+    def write_usage(self, parser, fp):
+        if any(len(o.option_strings) for o in parser._actions):
+            fp.write(' <options>')
+        for option in parser._actions:
+            if option.option_strings:
+                continue
+            fp.write(' ' + option.metavar)
+
+    def write_options(self, parser, fp):
+        for group in parser._action_groups:
+            if group.title == 'Common options':
+                fp.write('\n\n`Common options`_\n')
+                fp.write('    |')
+            else:
+                self.write_options_group(group, fp)
+
+    def write_options_group(self, group, fp, with_title=True):
+        def is_positional_group(group):
+            return any(not o.option_strings for o in group._group_actions)
+
+        def get_help(option):
+            text = textwrap.dedent((option.help or '') % option.__dict__)
+            return '\n'.join('| ' + line for line in text.splitlines())
+
+        def shipout(text):
+            fp.write(textwrap.indent('\n'.join(text), ' ' * 4))
+
+        if not group._group_actions:
+            return
+
+        if with_title:
+            fp.write('\n\n')
+            fp.write(group.title + '\n')
+        text = []
+
+        if is_positional_group(group):
+            for option in group._group_actions:
+                text.append(option.metavar)
+                text.append(textwrap.indent(option.help or '', ' ' * 4))
+            shipout(text)
+            return
+
+        options = []
+        for option in group._group_actions:
+            if option.metavar:
+                option_fmt = '``%%s %s``' % option.metavar
+            else:
+                option_fmt = '``%s``'
+            option_str = ', '.join(option_fmt % s for s in option.option_strings)
+            options.append((option_str, option))
+        for option_str, option in options:
+            help = textwrap.indent(get_help(option), ' ' * 4)
+            text.append(option_str)
+            text.append(help)
+        shipout(text)
 
 
 class build_api(Command):