mirror of
https://github.com/borgbackup/borg.git
synced 2025-02-22 14:11:27 +00:00
docs: More documentation improvements
This commit is contained in:
Jonas Borgström
parent
2b91d6620a
commit
ead1511948
3 changed files with 103 additions and 85 deletions
|
|
@ -53,8 +53,7 @@ def do_serve(self, args):
|
|||
return RepositoryServer(restrict_to_paths=args.restrict_to_paths).serve()
|
||||
|
||||
def do_init(self, args):
|
||||
"""Initialize an empty repository
|
||||
"""
|
||||
"""Initialize an empty repository"""
|
||||
print('Initializing repository at "%s"' % args.repository.orig)
|
||||
repository = self.open_repository(args.repository, create=True)
|
||||
key = key_creator(repository, args)
|
||||
|
|
@ -65,8 +64,7 @@ def do_init(self, args):
|
|||
return self.exit_code
|
||||
|
||||
def do_check(self, args):
|
||||
"""Check repository consistency
|
||||
"""
|
||||
"""Check repository consistency"""
|
||||
repository = self.open_repository(args.repository)
|
||||
if args.repair:
|
||||
while not os.environ.get('ATTIC_CHECK_I_KNOW_WHAT_I_AM_DOING'):
|
||||
|
|
@ -87,16 +85,14 @@ def do_check(self, args):
|
|||
return 0
|
||||
|
||||
def do_change_passphrase(self, args):
|
||||
"""Change repository key file passphrase
|
||||
"""
|
||||
"""Change repository key file passphrase"""
|
||||
repository = self.open_repository(args.repository)
|
||||
manifest, key = Manifest.load(repository)
|
||||
key.change_passphrase()
|
||||
return 0
|
||||
|
||||
def do_create(self, args):
|
||||
"""Create new archive
|
||||
"""
|
||||
"""Create new archive"""
|
||||
t0 = datetime.now()
|
||||
repository = self.open_repository(args.archive)
|
||||
manifest, key = Manifest.load(repository)
|
||||
|
|
@ -186,8 +182,7 @@ def _process(self, archive, cache, excludes, skip_inodes, path, restrict_dev):
|
|||
self.print_error('Unknown file type: %s', path)
|
||||
|
||||
def do_extract(self, args):
|
||||
"""Extract archive contents
|
||||
"""
|
||||
"""Extract archive contents"""
|
||||
repository = self.open_repository(args.archive)
|
||||
manifest, key = Manifest.load(repository)
|
||||
archive = Archive(repository, key, manifest, args.archive.archive,
|
||||
|
|
@ -217,8 +212,7 @@ def do_extract(self, args):
|
|||
return self.exit_code
|
||||
|
||||
def do_delete(self, args):
|
||||
"""Delete archive
|
||||
"""
|
||||
"""Delete an existing archive"""
|
||||
repository = self.open_repository(args.archive)
|
||||
manifest, key = Manifest.load(repository)
|
||||
cache = Cache(repository, key, manifest)
|
||||
|
|
@ -233,8 +227,7 @@ def do_delete(self, args):
|
|||
return self.exit_code
|
||||
|
||||
def do_mount(self, args):
|
||||
"""Mount archive or an entire repository as a FUSE fileystem
|
||||
"""
|
||||
"""Mount archive or an entire repository as a FUSE fileystem"""
|
||||
try:
|
||||
from attic.fuse import AtticOperations
|
||||
except ImportError:
|
||||
|
|
@ -295,8 +288,7 @@ def do_list(self, args):
|
|||
return self.exit_code
|
||||
|
||||
def do_info(self, args):
|
||||
"""Show archive details such as disk space used
|
||||
"""
|
||||
"""Show archive details such as disk space used"""
|
||||
repository = self.open_repository(args.archive)
|
||||
manifest, key = Manifest.load(repository)
|
||||
cache = Cache(repository, key, manifest)
|
||||
|
|
@ -313,8 +305,7 @@ def do_info(self, args):
|
|||
return self.exit_code
|
||||
|
||||
def do_prune(self, args):
|
||||
"""Prune repository archives according to specified rules
|
||||
"""
|
||||
"""Prune repository archives according to specified rules"""
|
||||
repository = self.open_repository(args.repository)
|
||||
manifest, key = Manifest.load(repository)
|
||||
cache = Cache(repository, key, manifest)
|
||||
|
|
@ -395,7 +386,13 @@ def do_help(self, parser, commands, args):
|
|||
elif args.topic in self.helptext:
|
||||
print(self.helptext[args.topic])
|
||||
elif args.topic in commands:
|
||||
commands[args.topic].print_help()
|
||||
if args.epilog_only:
|
||||
print(commands[args.topic].epilog)
|
||||
elif args.usage_only:
|
||||
commands[args.topic].epilog = None
|
||||
commands[args.topic].print_help()
|
||||
else:
|
||||
commands[args.topic].print_help()
|
||||
else:
|
||||
parser.error('No help available on %s' % (args.topic,))
|
||||
return self.exit_code
|
||||
|
|
@ -445,9 +442,14 @@ def run(self, args=None):
|
|||
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')
|
||||
|
||||
init_epilog = textwrap.dedent("""
|
||||
This command initializes an empty repository. A repository is a filesystem
|
||||
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],
|
||||
description=self.do_init.__doc__)
|
||||
description=self.do_init.__doc__, epilog=init_epilog,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
subparser.set_defaults(func=self.do_init)
|
||||
subparser.add_argument('repository', metavar='REPOSITORY',
|
||||
type=location_validator(archive=False),
|
||||
|
|
@ -484,17 +486,30 @@ def run(self, args=None):
|
|||
default=False,
|
||||
help='attempt to repair any inconsistencies found')
|
||||
|
||||
change_passphrase_epilog = textwrap.dedent("""
|
||||
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],
|
||||
description=self.do_change_passphrase.__doc__)
|
||||
description=self.do_change_passphrase.__doc__,
|
||||
epilog=change_passphrase_epilog,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
subparser.set_defaults(func=self.do_change_passphrase)
|
||||
subparser.add_argument('repository', metavar='REPOSITORY',
|
||||
type=location_validator(archive=False))
|
||||
|
||||
create_epilog = '''See "attic help patterns" for more help on exclude patterns.'''
|
||||
create_epilog = textwrap.dedent("""
|
||||
This command creates a backup archive containing all files found while recursively
|
||||
traversing all paths specified. The archive will consume almost no disk space for
|
||||
files or parts of files that have already been stored in other archives.
|
||||
|
||||
See "attic help patterns" for more help on exclude patterns.
|
||||
""")
|
||||
|
||||
subparser = subparsers.add_parser('create', parents=[common_parser],
|
||||
description=self.do_create.__doc__,
|
||||
epilog=create_epilog)
|
||||
epilog=create_epilog,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
subparser.set_defaults(func=self.do_create)
|
||||
subparser.add_argument('-s', '--stats', dest='stats',
|
||||
action='store_true', default=False,
|
||||
|
|
@ -520,11 +535,18 @@ def run(self, args=None):
|
|||
subparser.add_argument('paths', metavar='PATH', nargs='+', type=str,
|
||||
help='paths to archive')
|
||||
|
||||
extract_epilog = '''See "attic help patterns" for more help on exclude patterns.'''
|
||||
extract_epilog = textwrap.dedent("""
|
||||
This command extracts the contents of an archive. By default the entire
|
||||
archive is extracted but a subset of files and directories can be selected
|
||||
by passing a list of ``PATHs`` as arguments. The file selection can further
|
||||
be restricted by using the ``--exclude`` option.
|
||||
|
||||
See "attic help patterns" for more help on exclude patterns.
|
||||
""")
|
||||
subparser = subparsers.add_parser('extract', parents=[common_parser],
|
||||
description=self.do_extract.__doc__,
|
||||
epilog=extract_epilog)
|
||||
epilog=extract_epilog,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
subparser.set_defaults(func=self.do_extract)
|
||||
subparser.add_argument('-n', '--dry-run', dest='dry_run',
|
||||
default=False, action='store_true',
|
||||
|
|
@ -544,8 +566,14 @@ def run(self, args=None):
|
|||
subparser.add_argument('paths', metavar='PATH', nargs='*', type=str,
|
||||
help='paths to extract')
|
||||
|
||||
delete_epilog = textwrap.dedent("""
|
||||
This command deletes an archive from the repository. Any disk space not
|
||||
shared with any other existing archive is also reclaimed.
|
||||
""")
|
||||
subparser = subparsers.add_parser('delete', parents=[common_parser],
|
||||
description=self.do_delete.__doc__)
|
||||
description=self.do_delete.__doc__,
|
||||
epilog=delete_epilog,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
subparser.set_defaults(func=self.do_delete)
|
||||
subparser.add_argument('-s', '--stats', dest='stats',
|
||||
action='store_true', default=False,
|
||||
|
|
@ -554,14 +582,26 @@ def run(self, args=None):
|
|||
type=location_validator(archive=True),
|
||||
help='archive to delete')
|
||||
|
||||
list_epilog = textwrap.dedent("""
|
||||
This command lists the contents of a repository or an archive.
|
||||
""")
|
||||
subparser = subparsers.add_parser('list', parents=[common_parser],
|
||||
description=self.do_list.__doc__)
|
||||
description=self.do_list.__doc__,
|
||||
epilog=list_epilog,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
subparser.set_defaults(func=self.do_list)
|
||||
subparser.add_argument('src', metavar='REPOSITORY_OR_ARCHIVE', type=location_validator(),
|
||||
help='repository/archive to list contents of')
|
||||
|
||||
mount_epilog = textwrap.dedent("""
|
||||
This command mounts an archive as a FUSE filesystem. This can be useful for
|
||||
browsing an archive or restoring individual files. Unless the ``--foreground``
|
||||
option is given the command will run in the background until the filesystem
|
||||
is ``umounted``.
|
||||
""")
|
||||
subparser = subparsers.add_parser('mount', parents=[common_parser],
|
||||
description=self.do_mount.__doc__)
|
||||
description=self.do_mount.__doc__,
|
||||
epilog=mount_epilog,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
subparser.set_defaults(func=self.do_mount)
|
||||
subparser.add_argument('src', metavar='REPOSITORY_OR_ARCHIVE', type=location_validator(),
|
||||
help='repository/archive to mount')
|
||||
|
|
@ -573,35 +613,45 @@ def run(self, args=None):
|
|||
subparser.add_argument('-o', dest='options', type=str,
|
||||
help='Extra mount options')
|
||||
|
||||
info_epilog = textwrap.dedent("""
|
||||
This command displays some detailed information about the specified archive.
|
||||
""")
|
||||
subparser = subparsers.add_parser('info', parents=[common_parser],
|
||||
description=self.do_info.__doc__)
|
||||
description=self.do_info.__doc__,
|
||||
epilog=info_epilog,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
subparser.set_defaults(func=self.do_info)
|
||||
subparser.add_argument('archive', metavar='ARCHIVE',
|
||||
type=location_validator(archive=True),
|
||||
help='archive to display information about')
|
||||
|
||||
prune_epilog = '''The prune command prunes a repository by deleting archives
|
||||
not matching any of the specified retention options. This command is normally
|
||||
used by automated backup scripts wanting to keep a certain number of historic
|
||||
backups. As an example, "-d 7" means to keep the latest backup on each day
|
||||
for 7 days. Days without backups do not count towards the total. The rules
|
||||
are applied from hourly to yearly, and backups selected by previous rules do
|
||||
not count towards those of later rules. The time that each backup completes
|
||||
is used for pruning purposes. Dates and times are interpreted in
|
||||
prune_epilog = textwrap.dedent("""
|
||||
The prune command prunes a repository by deleting archives not matching
|
||||
any of the specified retention options. This command is normally used by
|
||||
automated backup scripts wanting to keep a certain number of historic backups.
|
||||
|
||||
As an example, "-d 7" means to keep the latest backup on each day for 7 days.
|
||||
Days without backups do not count towards the total.
|
||||
The rules are applied from hourly to yearly, and backups selected by previous
|
||||
rules do not count towards those of later rules. The time that each backup
|
||||
completes is used for pruning purposes. Dates and times are interpreted in
|
||||
the local timezone, and weeks go from Monday to Sunday. Specifying a
|
||||
negative number of archives to keep means that there is no limit.
|
||||
|
||||
The "--keep-within" option takes an argument of the form "<int><char>",
|
||||
where char is "H", "d", "w", "m", "y". For example, "--keep-within 2d" means
|
||||
to keep all archives that were created within the past 48 hours.
|
||||
"1m" is taken to mean "31d". The archives kept with this option do not
|
||||
count towards the totals specified by any other options. If a
|
||||
prefix is set with -p, then only archives that start with the prefix are
|
||||
considered for deletion and only those archives count towards the totals
|
||||
specified by the rules.'''
|
||||
count towards the totals specified by any other options.
|
||||
|
||||
If a prefix is set with -p, then only archives that start with the prefix are
|
||||
considered for deletion and only those archives count towards the totals
|
||||
specified by the rules.
|
||||
""")
|
||||
subparser = subparsers.add_parser('prune', parents=[common_parser],
|
||||
description=self.do_prune.__doc__,
|
||||
epilog=prune_epilog)
|
||||
epilog=prune_epilog,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
subparser.set_defaults(func=self.do_prune)
|
||||
subparser.add_argument('-n', '--dry-run', dest='dry_run',
|
||||
default=False, action='store_true',
|
||||
|
|
@ -629,8 +679,11 @@ def run(self, args=None):
|
|||
|
||||
subparser = subparsers.add_parser('help', parents=[common_parser],
|
||||
description='Extra help')
|
||||
subparser.set_defaults(
|
||||
func=functools.partial(self.do_help, parser, subparsers.choices))
|
||||
subparser.add_argument('--epilog-only', dest='epilog_only',
|
||||
action='store_true', default=False)
|
||||
subparser.add_argument('--usage-only', dest='usage_only',
|
||||
action='store_true', default=False)
|
||||
subparser.set_defaults(func=functools.partial(self.do_help, parser, subparsers.choices))
|
||||
subparser.add_argument('topic', metavar='TOPIC', type=str, nargs='?',
|
||||
help='additional help on TOPIC')
|
||||
|
||||
|
|
|
|||
|
|
@ -7,6 +7,7 @@ for cmd in change-passphrase check create delete extract info init list mount pr
|
|||
LINE=`echo -n attic $cmd | tr 'a-z- ' '-'`
|
||||
echo -e ".. _attic_$cmd:\n" > $FILENAME
|
||||
echo -e "attic $cmd\n$LINE\n::\n\n" >> $FILENAME
|
||||
attic $cmd -h | sed -e 's/^/ /' >> $FILENAME
|
||||
echo -e "\nDescription\n~~~~~~~~~~~\n\n" >> $FILENAME
|
||||
attic help $cmd --usage-only | sed -e 's/^/ /' >> $FILENAME
|
||||
echo -e "\nDescription\n~~~~~~~~~~~\n" >> $FILENAME
|
||||
attic help $cmd --epilog-only >> $FILENAME
|
||||
done
|
||||
|
|
|
|||
|
|
@ -17,11 +17,6 @@ messages as it is processing.
|
|||
|
||||
.. include:: usage/init.rst.inc
|
||||
|
||||
This command initializes an empty :ref:`repository <repository_def>`.
|
||||
A repository is a filesystem directory
|
||||
containing the deduplicated data from zero or more archives.
|
||||
Encryption is enabled at repository initialization time.
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
::
|
||||
|
|
@ -38,11 +33,6 @@ Examples
|
|||
|
||||
.. include:: usage/create.rst.inc
|
||||
|
||||
This command creates a backup archive containing all files found while
|
||||
recursively traversing all paths specified. The archive will consume almost
|
||||
no disk space for files or parts of files that have already been stored in
|
||||
other archives.
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
::
|
||||
|
|
@ -63,11 +53,6 @@ Examples
|
|||
|
||||
.. include:: usage/extract.rst.inc
|
||||
|
||||
This command extracts the contents of an archive. By default the entire
|
||||
archive is extracted but a subset of files and directories can be selected
|
||||
by passing a list of ``PATHs`` as arguments. The file selection can further
|
||||
be restricted by using the ``--exclude`` option.
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
::
|
||||
|
|
@ -88,14 +73,8 @@ Examples
|
|||
|
||||
.. include:: usage/delete.rst.inc
|
||||
|
||||
This command deletes an archive from the repository. Any disk space not
|
||||
shared with any other existing archive is also reclaimed.
|
||||
|
||||
|
||||
.. include:: usage/list.rst.inc
|
||||
|
||||
This command lists the contents of a repository or an archive.
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
::
|
||||
|
|
@ -118,11 +97,6 @@ Examples
|
|||
|
||||
.. include:: usage/prune.rst.inc
|
||||
|
||||
The ``prune`` command prunes a repository by deleting archives not matching
|
||||
any of the specified retention options. This command is normally
|
||||
used by automated backup scripts wanting to keep a certain number of historic
|
||||
backups.
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
::
|
||||
|
|
@ -144,8 +118,6 @@ Examples
|
|||
|
||||
.. include:: usage/info.rst.inc
|
||||
|
||||
This command displays some detailed information about the specified archive.
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
::
|
||||
|
|
@ -165,11 +137,6 @@ Examples
|
|||
|
||||
.. include:: usage/mount.rst.inc
|
||||
|
||||
This command mounts an archive as a FUSE filesystem. This can be useful for
|
||||
browsing an archive or restoring individual files. Unless the ``--foreground``
|
||||
option is given the command will run in the background until the filesystem
|
||||
is ``umounted``.
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
::
|
||||
|
|
@ -182,15 +149,12 @@ Examples
|
|||
|
||||
.. include:: usage/change-passphrase.rst.inc
|
||||
|
||||
The key files used for repository encryption are optionally passphrase
|
||||
protected. This command can be used to change this passphrase.
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
::
|
||||
|
||||
# Create a key file protected repository
|
||||
$ attic init --key-file /tmp/encrypted-repo
|
||||
$ attic init --encryption=keyfile /tmp/encrypted-repo
|
||||
Initializing repository at "/tmp/encrypted-repo"
|
||||
Enter passphrase (empty for no passphrase):
|
||||
Enter same passphrase again:
|
||||
|
|
|
|||
Loading…
Reference in a new issue