diff --git a/borg/archiver.py b/borg/archiver.py index 309950d0b..afb27cddb 100644 --- a/borg/archiver.py +++ b/borg/archiver.py @@ -823,8 +823,7 @@ class Archiver: re:^/home/[^/]\.tmp/ sh:/home/*/.thumbnails EOF - $ borg create --exclude-from exclude.txt backup / - ''') + $ borg create --exclude-from exclude.txt backup /\n\n''') helptext['placeholders'] = textwrap.dedent(''' Repository (or Archive) URLs and --prefix values support these placeholders: @@ -856,8 +855,7 @@ class Archiver: borg create /path/to/repo::{hostname}-{user}-{utcnow} ... borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ... - borg prune --prefix '{hostname}-' ... - ''') + borg prune --prefix '{hostname}-' ...\n\n''') def do_help(self, parser, commands, args): if not args.topic: diff --git a/borg/helpers.py b/borg/helpers.py index 7c340760a..56e336e0d 100644 --- a/borg/helpers.py +++ b/borg/helpers.py @@ -914,8 +914,7 @@ def yes(msg=None, false_msg=None, true_msg=None, default_msg=None, retry_msg=None, invalid_msg=None, env_msg=None, falsish=FALSISH, truish=TRUISH, defaultish=DEFAULTISH, default=False, retry=True, env_var_override=None, ofile=None, input=input): - """ - Output (usually a question) and let user input an answer. + """Output (usually a question) and let user input an answer. Qualifies the answer according to falsish, truish and defaultish as True, False or . If it didn't qualify and retry_msg is None (no retries wanted), return the default [which defaults to False]. Otherwise let user retry @@ -1083,7 +1082,7 @@ def log_multi(*msgs, level=logging.INFO): """ log multiple lines of text, each line by a separate logging call for cosmetic reasons - each positional argument may be a single or multiple lines (separated by \n) of text. + each positional argument may be a single or multiple lines (separated by newlines) of text. """ lines = [] for msg in msgs: diff --git a/borg/locking.py b/borg/locking.py index bc3660d61..3a88d1504 100644 --- a/borg/locking.py +++ b/borg/locking.py @@ -101,9 +101,11 @@ class NotMyLock(LockErrorT): class ExclusiveLock: """An exclusive Lock based on mkdir fs operation being atomic. - If possible, try to use the contextmanager here like: - with ExclusiveLock(...) as lock: - ... + If possible, try to use the contextmanager here like:: + + with ExclusiveLock(...) as lock: + ... + This makes sure the lock is released again if the block is left, no matter how (e.g. if an exception occurred). """ @@ -222,9 +224,11 @@ class UpgradableLock: noone is allowed reading) and read access to a resource needs a shared lock (multiple readers are allowed). - If possible, try to use the contextmanager here like: - with UpgradableLock(...) as lock: - ... + If possible, try to use the contextmanager here like:: + + with UpgradableLock(...) as lock: + ... + This makes sure the lock is released again if the block is left, no matter how (e.g. if an exception occurred). """ diff --git a/borg/shellpattern.py b/borg/shellpattern.py index 7cb8f2114..fe03d90b2 100644 --- a/borg/shellpattern.py +++ b/borg/shellpattern.py @@ -5,7 +5,7 @@ import os def translate(pat): """Translate a shell-style pattern to a regular expression. - The pattern may include "**" ( stands for the platform-specific path separator; "/" on POSIX systems) for + The pattern may include ``**`` ( stands for the platform-specific path separator; "/" on POSIX systems) for matching zero or more directory levels and "*" for matching zero or more arbitrary characters with the exception of any path separator. Wrap meta-characters in brackets for a literal match (i.e. "[?]" to match the literal character "?"). diff --git a/docs/api.rst b/docs/api.rst index 718cb58e0..31a22fbb3 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -6,50 +6,18 @@ API Documentation :members: :undoc-members: -.. automodule:: borg.upgrader - :members: - :undoc-members: - .. automodule:: borg.archive :members: :undoc-members: -.. automodule:: borg.fuse - :members: - :undoc-members: - -.. automodule:: borg.platform - :members: - :undoc-members: - -.. automodule:: borg.locking - :members: - :undoc-members: - -.. automodule:: borg.shellpattern - :members: - :undoc-members: - .. automodule:: borg.repository :members: :undoc-members: -.. automodule:: borg.lrucache - :members: - :undoc-members: - .. automodule:: borg.remote :members: :undoc-members: -.. automodule:: borg.xattr - :members: - :undoc-members: - -.. automodule:: borg.helpers - :members: - :undoc-members: - .. automodule:: borg.cache :members: :undoc-members: @@ -62,7 +30,31 @@ API Documentation :members: :undoc-members: -.. automodule:: borg.platform_darwin +.. automodule:: borg.helpers + :members: + :undoc-members: + +.. automodule:: borg.locking + :members: + :undoc-members: + +.. automodule:: borg.shellpattern + :members: + :undoc-members: + +.. automodule:: borg.lrucache + :members: + :undoc-members: + +.. automodule:: borg.fuse + :members: + :undoc-members: + +.. automodule:: borg.xattr + :members: + :undoc-members: + +.. automodule:: borg.platform :members: :undoc-members: @@ -75,7 +67,7 @@ API Documentation :undoc-members: .. automodule:: borg.compress - :members: + :members: get_compressor, Compressor, CompressorBase :undoc-members: .. automodule:: borg.chunker @@ -85,7 +77,3 @@ API Documentation .. automodule:: borg.crypto :members: :undoc-members: - -.. automodule:: borg.platform_freebsd - :members: - :undoc-members: diff --git a/docs/conf.py b/docs/conf.py index 72eb833ab..26d405d11 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,6 +55,8 @@ version = sw_version.split('-')[0] # The full version, including alpha/beta/rc tags. release = version +suppress_warnings = ['image.nonlocal_uri'] + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #language = None diff --git a/docs/resources.rst b/docs/resources.rst index 4ae184946..2ef0f021f 100644 --- a/docs/resources.rst +++ b/docs/resources.rst @@ -17,21 +17,15 @@ Some of them refer to attic, but you can do the same stuff (and more) with borgb - `TW's slides for borgbackup talks / lightning talks `_ (just grab the latest ones) -- "Attic / Borg Backup" talk from GPN 2015 (video, german audio, english slides): - `media.ccc.de `_ - or - `youtube `_ +- `Attic / Borg Backup talk from GPN 2015 (media.ccc.de) `_ +- `Attic / Borg Backup talk from GPN 2015 (youtube) `_ -- "Attic" talk from Easterhegg 2015 (video, german audio, english slides): - `media.ccc.de `_ - or - `youtube `_ +- `Attic talk from Easterhegg 2015 (media.ccc.de) `_ +- `Attic talk from Easterhegg 2015 (youtube) `_ -- "Attic Backup: Mount your encrypted backups over ssh", 2014 (video, english): - `youtube `_ +- `Attic Backup: Mount your encrypted backups over ssh (youtube) `_ -- "Evolution of Borg", Oct 2015 (gource visualization of attic and borg development): - `youtube `_ +- `Evolution of Borg (youtube) `_ Software -------- diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index 30d8c4591..f6618b677 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -1,48 +1,9 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! -.. _borg_placeholders: - -borg help placeholders -~~~~~~~~~~~~~~~~~~~~~~ -:: - - -Repository (or Archive) URLs and --prefix values support these placeholders: - -{hostname} - - The (short) hostname of the machine. - -{fqdn} - - The full name of the machine. - -{now} - - The current local date and time. - -{utcnow} - - The current UTC date and time. - -{user} - - The user name (or UID, if no name is available) of the user running borg. - -{pid} - - The current process ID. - -Examples:: - - borg create /path/to/repo::{hostname}-{user}-{utcnow} ... - borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ... - borg prune --prefix '{hostname}-' ... .. _borg_patterns: borg help patterns ~~~~~~~~~~~~~~~~~~ -:: Exclusion patterns support four separate styles, fnmatch, shell, regular @@ -131,3 +92,42 @@ Examples:: sh:/home/*/.thumbnails EOF $ borg create --exclude-from exclude.txt backup / + +.. _borg_placeholders: + +borg help placeholders +~~~~~~~~~~~~~~~~~~~~~~ + + +Repository (or Archive) URLs and --prefix values support these placeholders: + +{hostname} + + The (short) hostname of the machine. + +{fqdn} + + The full name of the machine. + +{now} + + The current local date and time. + +{utcnow} + + The current UTC date and time. + +{user} + + The user name (or UID, if no name is available) of the user running borg. + +{pid} + + The current process ID. + +Examples:: + + borg create /path/to/repo::{hostname}-{user}-{utcnow} ... + borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ... + borg prune --prefix '{hostname}-' ... + diff --git a/setup.py b/setup.py index 7aca6be78..b0103e06a 100644 --- a/setup.py +++ b/setup.py @@ -169,7 +169,7 @@ class build_usage(Command): params = {"topic": topic, "underline": '~' * len('borg help ' + topic)} doc.write(".. _borg_{topic}:\n\n".format(**params)) - doc.write("borg help {topic}\n{underline}\n::\n\n".format(**params)) + doc.write("borg help {topic}\n{underline}\n\n".format(**params)) doc.write(Archiver.helptext[topic]) else: params = {"command": command,