Rev for release.

Thanks! This will go out in the next release.

.gitignore

@@ -3,6 +3,7 @@
 *.swp
 .cache
 .coverage
+.pytest_cache
 .tox
 build
 dist

AUTHORS

@@ -4,6 +4,8 @@ Alexander Görtz: Python 3 compatibility
 Henning Schroeder: Copy editing
 Johannes Feichtner: Support for user hooks
 Michele Lazzeri: Custom archive names
+newtonne: Read encryption password from external file
 Robin `ypid` Schneider: Support additional options of Borg
 Scott Squires: Custom archive names
-Thomas LÉVEIL: Support for a keep_minutely prune option
+Thomas LÉVEIL: Support for a keep_minutely prune option. Support for the --json option
+Nick Whyte: Support prefix filtering for archive consistency checks

NEWS

@@ -1,3 +1,44 @@
+1.2.1
+ * Skip before/after backup hooks when only doing --prune, --check, --list, and/or --info.
+ * #71: Support for XDG_CONFIG_HOME environment variable for specifying alternate user ~/.config/
+   path.
+ * #74, #83: Support for Borg --json option via borgmatic command-line to --list archives or show
+   archive --info in JSON format, ideal for programmatic consumption.
+ * #38, #76: Upgrade ruamel.yaml compatibility version range and fix support for Python 3.7.
+ * #77: Skip non-"*.yaml" config filenames in /etc/borgmatic.d/ so as not to parse backup files,
+   editor swap files, etc.
+ * #81: Document user-defined hooks run before/after backup, or on error.
+ * Add code style guidelines to the documention.
+
+1.2.0
+ * #61: Support for Borg --list option via borgmatic command-line to list all archives.
+ * #61: Support for Borg --info option via borgmatic command-line to display summary information.
+ * #62: Update README to mention other ways of installing borgmatic.
+ * Support for Borg --prefix option for consistency checks via "prefix" option in borgmatic's
+   consistency configuration.
+ * Add introductory screencast link to documentation.
+ * #59: Ignore "check_last" and consistency "prefix" when "archives" not in consistency checks.
+ * #60: Add "Persistent" flag to systemd timer example.
+ * #63: Support for Borg --nobsdflags option to skip recording bsdflags (e.g. NODUMP, IMMUTABLE) in
+   archive.
+ * #69: Support for Borg prune --umask option using value of existing "umask" option in borgmatic's
+   storage configuration.
+ * Update tox.ini to only assume Python 3.x instead of Python 3.4 specifically.
+ * Add ~/.config/borgmatic/config.yaml to default configuration path probing.
+ * Document how to develop on and contribute to borgmatic.
+
+1.1.15
+ * Support for Borg BORG_PASSCOMMAND environment variable to read a password from an external file.
+ * Fix for Borg create error when using borgmatic's --dry-run and --verbosity options together.
+   Work-around for behavior introduced in Borg 1.1.3: https://github.com/borgbackup/borg/issues/3298
+ * #55: Fix for missing tags/releases on Gitea and GitHub project hosting.
+ * #56: Support for Borg --lock-wait option for the maximum wait for a repository/cache lock.
+ * #58: Support for using tilde in exclude_patterns to reference home directory.
+
+1.1.14
+ * #49: Fix for typo in --patterns-from option.
+ * #47: Support for Borg --dry-run option via borgmatic command-line.
+
 1.1.13
  * #54: Fix for incorrect consistency check flags passed to Borg when all three checks ("repository",
    "archives", and "extract") are specified in borgmatic configuration.

README.md

@@ -44,6 +44,8 @@ borgmatic is hosted at <https://torsion.org/borgmatic> with [source code
 available](https://projects.torsion.org/witten/borgmatic). It's also mirrored
 on [GitHub](https://github.com/witten/borgmatic) for convenience.
 
+<a href="https://asciinema.org/a/164143" target="_blank"><img src="https://asciinema.org/a/164143.png" width="100%" /></a>
+
 
 ## Installation
 
@@ -57,6 +59,12 @@ environment variable. See the [repository encryption
 section](https://borgbackup.readthedocs.io/en/latest/quickstart.html#repository-encryption)
 of the Quick Start for more info.
 
+Alternatively, the passphrase can be specified programatically by setting
+either the borgmatic `encryption_passcommand` configuration variable or the
+`BORG_PASSCOMMAND` environment variable. See the [Borg Security
+FAQ](http://borgbackup.readthedocs.io/en/stable/faq.html#how-can-i-specify-the-encryption-passphrase-programmatically)
+for more info.
+
 If the repository is on a remote host, make sure that your local root user has
 key-based ssh access to the desired user account on the remote host.
 
@@ -69,11 +77,18 @@ sudo pip3 install --upgrade borgmatic
 Note that your pip binary may have a different name than "pip3". Make sure
 you're using Python 3, as borgmatic does not support Python 2.
 
-### Docker
+### Other ways to install
 
-If you would like to run borgmatic within Docker, please take a look at
-[b3vis/borgmatic](https://hub.docker.com/r/b3vis/borgmatic/) for more
-information.
+ * [A borgmatic Docker image](https://hub.docker.com/r/b3vis/borgmatic/) based
+   on Alpine Linux.
+ * [Another borgmatic Docker image](https://hub.docker.com/r/coaxial/borgmatic/) based
+   on Alpine Linux, updated automatically whenever the Alpine image updates.
+ * [A borgmatic package for
+   Fedora](https://bodhi.fedoraproject.org/updates/?search=borgmatic).
+ * [A borgmatic package for Arch
+   Linux](https://aur.archlinux.org/packages/borgmatic/).
+ * [A borgmatic package for OpenBSD](http://ports.su/sysutils/borgmatic).
+<br><br>
 
 ## Configuration
 
@@ -83,6 +98,9 @@ After you install borgmatic, generate a sample configuration file:
 sudo generate-borgmatic-config
 ```
 
+If that command is not found, then it may be installed in a location that's
+not in your system `PATH`. Try looking in `/usr/local/bin/`.
+
 This generates a sample configuration file at /etc/borgmatic/config.yaml (by
 default). You should edit the file to suit your needs, as the values are just
 representative. All fields are optional except where indicated, so feel free
@@ -120,6 +138,31 @@ configuration paths on the command-line with borgmatic's `--config` option.
 See `borgmatic --help` for more information.
 
 
+### Hooks
+
+If you find yourself performing prepraration tasks before your backup runs, or
+cleanup work afterwards, borgmatic hooks may be of interest. They're simply
+shell commands that borgmatic executes for you at various points, and they're
+configured in the `hooks` section of your configuration file.
+
+For instance, you can specify `before_backup` hooks to dump a database to file
+before backing it up, and specify `after_backup` hooks to delete the temporary
+file afterwards.
+
+borgmatic hooks run once per configuration file. `before_backup` hooks run
+prior to backups of all repositories. `after_backup` hooks run afterwards, but
+not if an error occurs in a previous hook or in the backups themselves. And
+borgmatic runs `on_error` hooks if an error occurs.
+
+An important security note about hooks: borgmatic executes all hook commands
+with the user permissions of borgmatic itself. So to prevent potential shell
+injection or privilege escalation, do not forget to set secure permissions
+(chmod 0700) on borgmatic configuration files and scripts invoked by hooks.
+
+See the sample generated configuration file mentioned above for specifics
+about hook configuration syntax.
+
+
 ## Upgrading
 
 In general, all you should need to do to upgrade borgmatic is run the
@@ -257,7 +300,7 @@ configure a job runner to invoke it periodically.
 ### cron
 
 If you're using cron, download the [sample cron
-file](https://projects.torsion.org/witten/borgmatic/raw/master/sample/cron/borgmatic).
+file](https://projects.torsion.org/witten/borgmatic/src/master/sample/cron/borgmatic).
 Then, from the directory where you downloaded it:
 
 ```bash
@@ -286,17 +329,89 @@ Feel free to modify the timer file based on how frequently you'd like
 borgmatic to run.
 
 
-## Running tests
+## Support and contributing
 
-First install tox, which is used for setting up testing environments:
+### Issues
 
-```bash
-pip3 install tox
+You've got issues? Or an idea for a feature enhancement? We've got an [issue
+tracker](https://projects.torsion.org/witten/borgmatic/issues). In order to
+create a new issue or comment on an issue, you'll need to [login
+first](https://projects.torsion.org/user/login). Note that you can login with
+an existing GitHub account if you prefer.
+
+Other questions or comments? Contact <mailto:witten@torsion.org>.
+
+
+### Contributing
+
+If you'd like to contribute to borgmatic development, please feel free to
+submit a [Pull Request](https://projects.torsion.org/witten/borgmatic/pulls)
+or open an [issue](https://projects.torsion.org/witten/borgmatic/issues) first
+to discuss your idea. We also accept Pull Requests on GitHub, if that's more
+your thing. In general, contributions are very welcome. We don't bite! 
+
+
+### Code style
+
+Start with [PEP 8](https://www.python.org/dev/peps/pep-0008/). But then, apply
+the following deviations from it:
+
+ * For strings, prefer single quotes over double quotes.
+ * Limit all lines to a maximum of 100 characters.
+ * Use trailing commas within multiline values or argument lists.
+ * For multiline constructs, put opening and closing delimeters on lines
+   separate from their contents.
+ * Within multiline constructs, use standard four-space indentation. Don't align
+   indentation with an opening delimeter.
+
+
+### Development
+
+To get set up to hack on borgmatic, first clone master via HTTPS or SSH:
+
+```
+git clone https://projects.torsion.org/witten/borgmatic.git
 ```
 
-Then, to actually run tests, run:
+Or:
 
 ```bash
+git clone ssh://git@projects.torsion.org:3022/witten/borgmatic.git
+```
+
+Then, install borgmatic
+"[editable](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs)"
+so that you can easily run borgmatic commands while you're hacking on them to
+make sure your changes work.
+
+```bash
+cd borgmatic/
+pip3 install --editable --user .
+```
+
+Note that this will typically install the borgmatic commands into
+`~/.local/bin`, which may or may not be on your PATH. There are other ways to
+install borgmatic editable as well, for instance into the system Python
+install (so without `--user`, as root), or even into a
+[virtualenv](https://virtualenv.pypa.io/en/stable/). How or where you install
+borgmatic is up to you, but generally an editable install makes development
+and testing easier.
+
+
+### Running tests
+
+Assuming you've cloned the borgmatic source code as described above, and
+you're in the `borgmatic/` working copy, install tox, which is used for
+setting up testing environments:
+
+```bash
+sudo pip3 install tox
+```
+
+Finally, to actually run tests, run:
+
+```bash
+cd borgmatic
 tox
 ```
 
@@ -335,14 +450,3 @@ YAML library. If so, not to worry. borgmatic should install and function
 correctly even without the C YAML library. And borgmatic won't be any faster
 with the C library present, so you don't need to go out of your way to install
 it.
-
-
-## Issues and feedback
-
-Got an issue or an idea for a feature enhancement? Check out the [borgmatic
-issue tracker](https://projects.torsion.org/witten/borgmatic/issues). In order
-to create a new issue or comment on an issue, you'll need to [login
-first](https://projects.torsion.org/user/login). Note that you can login with
-an existing GitHub account if you prefer.
-
-Other questions or comments? Contact <mailto:witten@torsion.org>.

borgmatic/borg/check.py

@@ -7,6 +7,7 @@ from borgmatic.verbosity import VERBOSITY_SOME, VERBOSITY_LOTS
 
 
 DEFAULT_CHECKS = ('repository', 'archives')
+DEFAULT_PREFIX = '{hostname}-'
 
 
 logger = logging.getLogger(__name__)
@@ -34,7 +35,7 @@ def _parse_checks(consistency_config):
     return tuple(check for check in checks if check.lower() not in ('disabled', '')) or DEFAULT_CHECKS
 
 
-def _make_check_flags(checks, check_last=None):
+def _make_check_flags(checks, check_last=None, prefix=None):
     '''
     Given a parsed sequence of checks, transform it into tuple of command-line flags.
 
@@ -47,40 +48,59 @@ def _make_check_flags(checks, check_last=None):
         ('--repository-only',)
 
     However, if both "repository" and "archives" are in checks, then omit them from the returned
-    flags because Borg does both checks by default. Additionally, if a check_last value is given,
-    a "--last" flag will be added.
+    flags because Borg does both checks by default.
+
+    Additionally, if a check_last value is given and "archives" is in checks, then include a
+    "--last" flag. And if a prefix value is given and "archives" is in checks, then include a
+    "--prefix" flag.
     '''
-    last_flag = ('--last', str(check_last)) if check_last else ()
+    if 'archives' in checks:
+        last_flags = ('--last', str(check_last)) if check_last else ()
+        prefix_flags = ('--prefix', prefix) if prefix else ('--prefix', DEFAULT_PREFIX)
+    else:
+        last_flags = ()
+        prefix_flags = ()
+        if check_last:
+            logger.warn('Ignoring check_last option, as "archives" is not in consistency checks.')
+        if prefix:
+            logger.warn('Ignoring consistency prefix option, as "archives" is not in consistency checks.')
+        
     if set(DEFAULT_CHECKS).issubset(set(checks)):
-        return last_flag
+        return last_flags + prefix_flags
 
     return tuple(
         '--{}-only'.format(check) for check in checks
         if check in DEFAULT_CHECKS
-    ) + last_flag
+    ) + last_flags + prefix_flags
 
 
-def check_archives(verbosity, repository, consistency_config, local_path='borg', remote_path=None):
+def check_archives(verbosity, repository, storage_config, consistency_config, local_path='borg',
+                   remote_path=None):
     '''
-    Given a verbosity flag, a local or remote repository path, a consistency config dict, and a
-    local/remote commands to run, check the contained Borg archives for consistency.
+    Given a verbosity flag, a local or remote repository path, a storage config dict, a consistency
+    config dict, and a local/remote commands to run, check the contained Borg archives for
+    consistency.
 
     If there are no consistency checks to run, skip running them.
     '''
     checks = _parse_checks(consistency_config)
     check_last = consistency_config.get('check_last', None)
+    lock_wait = None
 
     if set(checks).intersection(set(DEFAULT_CHECKS)):
         remote_path_flags = ('--remote-path', remote_path) if remote_path else ()
+        lock_wait = storage_config.get('lock_wait', None)
+        lock_wait_flags = ('--lock-wait', str(lock_wait)) if lock_wait else ()
         verbosity_flags = {
             VERBOSITY_SOME: ('--info',),
             VERBOSITY_LOTS: ('--debug',),
         }.get(verbosity, ())
+        prefix = consistency_config.get('prefix')
 
         full_command = (
             local_path, 'check',
             repository,
-        ) + _make_check_flags(checks, check_last) + remote_path_flags + verbosity_flags
+        ) + _make_check_flags(checks, check_last, prefix) + remote_path_flags + lock_wait_flags + verbosity_flags
 
         # The check command spews to stdout/stderr even without the verbose flag. Suppress it.
         stdout = None if verbosity_flags else open(os.devnull, 'w')
@@ -89,4 +109,4 @@ def check_archives(verbosity, repository, consistency_config, local_path='borg',
         subprocess.check_call(full_command, stdout=stdout, stderr=subprocess.STDOUT)
 
     if 'extract' in checks:
-        extract.extract_last_archive_dry_run(verbosity, repository, local_path, remote_path)
+        extract.extract_last_archive_dry_run(verbosity, repository, lock_wait, local_path, remote_path)

borgmatic/borg/create.py

@@ -12,6 +12,10 @@ logger = logging.getLogger(__name__)
 
 
 def initialize_environment(storage_config):
+    passcommand = storage_config.get('encryption_passcommand')
+    if passcommand:
+        os.environ['BORG_PASSCOMMAND'] = passcommand
+
     passphrase = storage_config.get('encryption_passphrase')
     if passphrase:
         os.environ['BORG_PASSPHRASE'] = passphrase
@@ -31,6 +35,22 @@ def _expand_directory(directory):
     return glob.glob(expanded_directory) or [expanded_directory]
 
 
+def _expand_directories(directories):
+    '''
+    Given a sequence of directory paths, expand tildes and globs in each one. Return all the
+    resulting directories as a single flattened tuple.
+    '''
+    if directories is None:
+        return ()
+
+    return tuple(
+        itertools.chain.from_iterable(
+            _expand_directory(directory)
+            for directory in directories
+        )
+    )
+
+
 def _write_pattern_file(patterns=None):
     '''
     Given a sequence of patterns, write them to a named temporary file and return it. Return None
@@ -57,7 +77,7 @@ def _make_pattern_flags(location_config, pattern_filename=None):
 
     return tuple(
         itertools.chain.from_iterable(
-            ('--pattern-from', pattern_filename)
+            ('--patterns-from', pattern_filename)
             for pattern_filename in pattern_filenames
         )
     )
@@ -85,55 +105,55 @@ def _make_exclude_flags(location_config, exclude_filename=None):
 
 
 def create_archive(
-    verbosity, repository, location_config, storage_config, local_path='borg', remote_path=None,
+    verbosity, dry_run, repository, location_config, storage_config, local_path='borg', remote_path=None,
 ):
     '''
-    Given a vebosity flag, a local or remote repository path, a location config dict, and a storage
-    config dict, create a Borg archive.
+    Given vebosity/dry-run flags, a local or remote repository path, a location config dict, and a
+    storage config dict, create a Borg archive.
     '''
-    sources = tuple(
-        itertools.chain.from_iterable(
-            _expand_directory(directory)
-            for directory in location_config['source_directories']
-        )
-    )
+    sources = _expand_directories(location_config['source_directories'])
 
     pattern_file = _write_pattern_file(location_config.get('patterns'))
-    pattern_flags = _make_pattern_flags(
-        location_config,
-        pattern_file.name if pattern_file else None,
-    )
-    exclude_file = _write_pattern_file(location_config.get('exclude_patterns'))
-    exclude_flags = _make_exclude_flags(
-        location_config,
-        exclude_file.name if exclude_file else None,
-    )
+    exclude_file = _write_pattern_file(_expand_directories(location_config.get('exclude_patterns')))
     compression = storage_config.get('compression', None)
-    compression_flags = ('--compression', compression) if compression else ()
     remote_rate_limit = storage_config.get('remote_rate_limit', None)
-    remote_rate_limit_flags = ('--remote-ratelimit', str(remote_rate_limit)) if remote_rate_limit else ()
     umask = storage_config.get('umask', None)
-    umask_flags = ('--umask', str(umask)) if umask else ()
-    one_file_system_flags = ('--one-file-system',) if location_config.get('one_file_system') else ()
+    lock_wait = storage_config.get('lock_wait', None)
     files_cache = location_config.get('files_cache')
-    files_cache_flags = ('--files-cache', files_cache) if files_cache else ()
-    remote_path_flags = ('--remote-path', remote_path) if remote_path else ()
-    verbosity_flags = {
-        VERBOSITY_SOME: ('--info', '--stats',),
-        VERBOSITY_LOTS: ('--debug', '--list', '--stats'),
-    }.get(verbosity, ())
     default_archive_name_format = '{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}'
     archive_name_format = storage_config.get('archive_name_format', default_archive_name_format)
 
     full_command = (
-        local_path, 'create',
-        '{repository}::{archive_name_format}'.format(
-            repository=repository,
-            archive_name_format=archive_name_format,
-        ),
-    ) + sources + pattern_flags + exclude_flags + compression_flags + remote_rate_limit_flags + \
-        one_file_system_flags + files_cache_flags + remote_path_flags + umask_flags + \
-        verbosity_flags
+        (
+            local_path, 'create',
+            '{repository}::{archive_name_format}'.format(
+                repository=repository,
+                archive_name_format=archive_name_format,
+            ),
+        )
+        + sources
+        + _make_pattern_flags(
+            location_config,
+            pattern_file.name if pattern_file else None,
+        )
+        + _make_exclude_flags(
+            location_config,
+            exclude_file.name if exclude_file else None,
+        )
+        + (('--compression', compression) if compression else ())
+        + (('--remote-ratelimit', str(remote_rate_limit)) if remote_rate_limit else ())
+        + (('--one-file-system',) if location_config.get('one_file_system') else ())
+        + (('--nobsdflags',) if location_config.get('bsd_flags') is False else ())
+        + (('--files-cache', files_cache) if files_cache else ())
+        + (('--remote-path', remote_path) if remote_path else ())
+        + (('--umask', str(umask)) if umask else ())
+        + (('--lock-wait', str(lock_wait)) if lock_wait else ())
+        + {
+            VERBOSITY_SOME: ('--info',) if dry_run else ('--info', '--stats',),
+            VERBOSITY_LOTS: ('--debug', '--list',) if dry_run else ('--debug', '--list', '--stats',),
+        }.get(verbosity, ())
+        + (('--dry-run',) if dry_run else ())
+    )
 
     logger.debug(' '.join(full_command))
     subprocess.check_call(full_command)

borgmatic/borg/extract.py

@@ -8,12 +8,13 @@ from borgmatic.verbosity import VERBOSITY_SOME, VERBOSITY_LOTS
 logger = logging.getLogger(__name__)
 
 
-def extract_last_archive_dry_run(verbosity, repository, local_path='borg', remote_path=None):
+def extract_last_archive_dry_run(verbosity, repository, lock_wait=None, local_path='borg', remote_path=None):
     '''
     Perform an extraction dry-run of just the most recent archive. If there are no archives, skip
     the dry-run.
     '''
     remote_path_flags = ('--remote-path', remote_path) if remote_path else ()
+    lock_wait_flags = ('--lock-wait', str(lock_wait)) if lock_wait else ()
     verbosity_flags = {
         VERBOSITY_SOME: ('--info',),
         VERBOSITY_LOTS: ('--debug',),
@@ -23,7 +24,7 @@ def extract_last_archive_dry_run(verbosity, repository, local_path='borg', remot
         local_path, 'list',
         '--short',
         repository,
-    ) + remote_path_flags + verbosity_flags
+    ) + remote_path_flags + lock_wait_flags + verbosity_flags
 
     list_output = subprocess.check_output(full_list_command).decode(sys.stdout.encoding)
 
@@ -39,7 +40,7 @@ def extract_last_archive_dry_run(verbosity, repository, local_path='borg', remot
             repository=repository,
             last_archive_name=last_archive_name,
         ),
-    ) + remote_path_flags + verbosity_flags + list_flag
+    ) + remote_path_flags + lock_wait_flags + verbosity_flags + list_flag
 
     logger.debug(' '.join(full_extract_command))
     subprocess.check_call(full_extract_command)

borgmatic/borg/info.py

@@ -0,0 +1,33 @@
+import logging
+import subprocess
+
+from borgmatic.verbosity import VERBOSITY_SOME, VERBOSITY_LOTS
+
+
+logger = logging.getLogger(__name__)
+
+
+def display_archives_info(
+    verbosity, repository, storage_config, local_path='borg', remote_path=None, json=False
+):
+    '''
+    Given a verbosity flag, a local or remote repository path, and a storage config dict,
+    display summary information for Borg archives in the repository.
+    '''
+    lock_wait = storage_config.get('lock_wait', None)
+
+    full_command = (
+        (local_path, 'info', repository)
+        + (('--remote-path', remote_path) if remote_path else ())
+        + (('--lock-wait', str(lock_wait)) if lock_wait else ())
+        + (('--json',) if json else ())
+        + {
+            VERBOSITY_SOME: ('--info',),
+            VERBOSITY_LOTS: ('--debug',),
+        }.get(verbosity, ())
+    )
+
+    logger.debug(' '.join(full_command))
+
+    output = subprocess.check_output(full_command)
+    return output.decode() if output is not None else None

borgmatic/borg/list.py

@@ -0,0 +1,33 @@
+import logging
+import subprocess
+
+from borgmatic.verbosity import VERBOSITY_SOME, VERBOSITY_LOTS
+
+
+logger = logging.getLogger(__name__)
+
+
+def list_archives(
+    verbosity, repository, storage_config, local_path='borg', remote_path=None, json=False
+):
+    '''
+    Given a verbosity flag, a local or remote repository path, and a storage config dict,
+    list Borg archives in the repository.
+    '''
+    lock_wait = storage_config.get('lock_wait', None)
+
+    full_command = (
+        (local_path, 'list', repository)
+        + (('--remote-path', remote_path) if remote_path else ())
+        + (('--lock-wait', str(lock_wait)) if lock_wait else ())
+        + (('--json',) if json else ())
+        + {
+            VERBOSITY_SOME: ('--info',),
+            VERBOSITY_LOTS: ('--debug',),
+        }.get(verbosity, ())
+    )
+
+    logger.debug(' '.join(full_command))
+
+    output = subprocess.check_output(full_command)
+    return output.decode() if output is not None else None

borgmatic/borg/prune.py

@@ -32,25 +32,34 @@ def _make_prune_flags(retention_config):
     )
 
 
-def prune_archives(verbosity, repository, retention_config, local_path='borg', remote_path=None):
+def prune_archives(verbosity, dry_run, repository, storage_config, retention_config,
+                   local_path='borg', remote_path=None):
     '''
-    Given a verbosity flag, a local or remote repository path, a retention config dict, prune Borg
-    archives according the the retention policy specified in that configuration.
+    Given verbosity/dry-run flags, a local or remote repository path, a storage config dict, and a
+    retention config dict, prune Borg archives according to the retention policy specified in that
+    configuration.
     '''
-    remote_path_flags = ('--remote-path', remote_path) if remote_path else ()
-    verbosity_flags = {
-        VERBOSITY_SOME: ('--info', '--stats',),
-        VERBOSITY_LOTS: ('--debug', '--stats', '--list'),
-    }.get(verbosity, ())
+    umask = storage_config.get('umask', None)
+    lock_wait = storage_config.get('lock_wait', None)
 
     full_command = (
-        local_path, 'prune',
-        repository,
-    ) + tuple(
-        element
-        for pair in _make_prune_flags(retention_config)
-        for element in pair
-    ) + remote_path_flags + verbosity_flags
+        (
+            local_path, 'prune',
+            repository,
+        ) + tuple(
+            element
+            for pair in _make_prune_flags(retention_config)
+            for element in pair
+        )
+        + (('--remote-path', remote_path) if remote_path else ())
+        + (('--umask', str(umask)) if umask else ())
+        + (('--lock-wait', str(lock_wait)) if lock_wait else ())
+        + {
+            VERBOSITY_SOME: ('--info', '--stats',),
+            VERBOSITY_LOTS: ('--debug', '--stats', '--list'),
+        }.get(verbosity, ())
+        + (('--dry-run',) if dry_run else ())
+    )
 
     logger.debug(' '.join(full_command))
     subprocess.check_call(full_command)

borgmatic/commands/borgmatic.py

@@ -1,11 +1,12 @@
-
 from argparse import ArgumentParser
+import json
 import logging
 import os
 from subprocess import CalledProcessError
 import sys
 
-from borgmatic.borg import check, create, prune
+from borgmatic.borg import check as borg_check, create as borg_create, prune as borg_prune, \
+     list as borg_list, info as borg_info
 from borgmatic.commands import hook
 from borgmatic.config import collect, convert, validate
 from borgmatic.signals import configure_signals
@@ -23,6 +24,8 @@ def parse_arguments(*arguments):
     Given command-line arguments with which this script was invoked, parse the arguments and return
     them as an ArgumentParser instance.
     '''
+    config_paths = collect.get_default_config_paths()
+
     parser = ArgumentParser(
         description=
             '''
@@ -35,8 +38,8 @@ def parse_arguments(*arguments):
         '-c', '--config',
         nargs='+',
         dest='config_paths',
-        default=collect.DEFAULT_CONFIG_PATHS,
-        help='Configuration filenames or directories, defaults to: {}'.format(' '.join(collect.DEFAULT_CONFIG_PATHS)),
+        default=config_paths,
+        help='Configuration filenames or directories, defaults to: {}'.format(' '.join(config_paths)),
     )
     parser.add_argument(
         '--excludes',
@@ -61,6 +64,31 @@ def parse_arguments(*arguments):
         action='store_true',
         help='Check archives for consistency',
     )
+    parser.add_argument(
+        '-l', '--list',
+        dest='list',
+        action='store_true',
+        help='List archives',
+    )
+    parser.add_argument(
+        '-i', '--info',
+        dest='info',
+        action='store_true',
+        help='Display summary information on archives',
+    )
+    parser.add_argument(
+        '--json',
+        dest='json',
+        default=False,
+        action='store_true',
+        help='Output results from the --list option as json',
+    )
+    parser.add_argument(
+        '-n', '--dry-run',
+        dest='dry_run',
+        action='store_true',
+        help='Go through the motions, but do not actually write to any repositories',
+    )
     parser.add_argument(
         '-v', '--verbosity',
         type=int,
@@ -69,14 +97,22 @@ def parse_arguments(*arguments):
 
     args = parser.parse_args(arguments)
 
-    # If any of the three action flags in the given parse arguments have been explicitly requested,
-    # leave them as-is. Otherwise, assume defaults: Mutate the given arguments to enable all the
-    # actions.
-    if not args.prune and not args.create and not args.check:
-        args.prune = True
-        args.create = True
-        args.check = True
+    if args.json and not (args.list or args.info):
+        raise ValueError('The --json option can only be used with the --list or --info options')
 
+    if args.json and args.list and args.info:
+        raise ValueError(
+            'With the --json option, options --list and --info cannot be used together'
+        )
+
+    # If any of the action flags are explicitly requested, leave them as-is. Otherwise, assume
+    # defaults: Mutate the given arguments to enable the default actions.
+    if args.prune or args.create or args.check or args.list or args.info:
+        return args
+
+    args.prune = True
+    args.create = True
+    args.check = True
     return args
 
 
@@ -95,46 +131,99 @@ def run_configuration(config_filename, args):  # pragma: no cover
     try:
         local_path = location.get('local_path', 'borg')
         remote_path = location.get('remote_path')
-        create.initialize_environment(storage)
-        hook.execute_hook(hooks.get('before_backup'), config_filename, 'pre-backup')
+        borg_create.initialize_environment(storage)
 
-        for unexpanded_repository in location['repositories']:
-            repository = os.path.expanduser(unexpanded_repository)
-            if args.prune:
-                logger.info('{}: Pruning archives'.format(repository))
-                prune.prune_archives(
-                    args.verbosity,
-                    repository,
-                    retention,
-                    local_path=local_path,
-                    remote_path=remote_path,
-                )
-            if args.create:
-                logger.info('{}: Creating archive'.format(repository))
-                create.create_archive(
-                    args.verbosity,
-                    repository,
-                    location,
-                    storage,
-                    local_path=local_path,
-                    remote_path=remote_path,
-                )
-            if args.check:
-                logger.info('{}: Running consistency checks'.format(repository))
-                check.check_archives(
-                    args.verbosity,
-                    repository,
-                    consistency,
-                    local_path=local_path,
-                    remote_path=remote_path,
-                )
+        if args.create:
+            hook.execute_hook(hooks.get('before_backup'), config_filename, 'pre-backup')
 
-        hook.execute_hook(hooks.get('after_backup'), config_filename, 'post-backup')
+        _run_commands(args, consistency, local_path, location, remote_path, retention, storage)
+
+        if args.create:
+            hook.execute_hook(hooks.get('after_backup'), config_filename, 'post-backup')
     except (OSError, CalledProcessError):
         hook.execute_hook(hooks.get('on_error'), config_filename, 'on-error')
         raise
 
 
+def _run_commands(args, consistency, local_path, location, remote_path, retention, storage):
+    json_results = []
+    for unexpanded_repository in location['repositories']:
+        _run_commands_on_repository(
+            args, consistency, json_results, local_path, location, remote_path, retention, storage,
+            unexpanded_repository,
+        )
+    if args.json:
+        sys.stdout.write(json.dumps(json_results))
+
+
+def _run_commands_on_repository(
+    args, consistency, json_results, local_path, location, remote_path,
+    retention, storage, unexpanded_repository,
+):  # pragma: no cover
+    repository = os.path.expanduser(unexpanded_repository)
+    dry_run_label = ' (dry run; not making any changes)' if args.dry_run else ''
+    if args.prune:
+        logger.info('{}: Pruning archives{}'.format(repository, dry_run_label))
+        borg_prune.prune_archives(
+            args.verbosity,
+            args.dry_run,
+            repository,
+            storage,
+            retention,
+            local_path=local_path,
+            remote_path=remote_path,
+        )
+    if args.create:
+        logger.info('{}: Creating archive{}'.format(repository, dry_run_label))
+        borg_create.create_archive(
+            args.verbosity,
+            args.dry_run,
+            repository,
+            location,
+            storage,
+            local_path=local_path,
+            remote_path=remote_path,
+        )
+    if args.check:
+        logger.info('{}: Running consistency checks'.format(repository))
+        borg_check.check_archives(
+            args.verbosity,
+            repository,
+            storage,
+            consistency,
+            local_path=local_path,
+            remote_path=remote_path,
+        )
+    if args.list:
+        logger.info('{}: Listing archives'.format(repository))
+        output = borg_list.list_archives(
+            args.verbosity,
+            repository,
+            storage,
+            local_path=local_path,
+            remote_path=remote_path,
+            json=args.json,
+        )
+        if args.json:
+            json_results.append(json.loads(output))
+        else:
+            sys.stdout.write(output)
+    if args.info:
+        logger.info('{}: Displaying summary info for archives'.format(repository))
+        output = borg_info.display_archives_info(
+            args.verbosity,
+            repository,
+            storage,
+            local_path=local_path,
+            remote_path=remote_path,
+            json=args.json,
+        )
+        if args.json:
+            json_results.append(json.loads(output))
+        else:
+            sys.stdout.write(output)
+
+
 def main():  # pragma: no cover
     try:
         configure_signals()

borgmatic/config/collect.py

@@ -1,20 +1,35 @@
 import os
 
 
-DEFAULT_CONFIG_PATHS = ['/etc/borgmatic/config.yaml', '/etc/borgmatic.d']
+def get_default_config_paths():
+    '''
+    Based on the value of the XDG_CONFIG_HOME and HOME environment variables, return a list of
+    default configuration paths. This includes both system-wide configuration and configuration in
+    the current user's home directory.
+    '''
+    user_config_directory = (
+        os.getenv('XDG_CONFIG_HOME') or os.path.expandvars(os.path.join('$HOME', '.config'))
+    )
+
+    return [
+        '/etc/borgmatic/config.yaml',
+        '/etc/borgmatic.d',
+        '%s/borgmatic/config.yaml' % user_config_directory,
+    ]
 
 
 def collect_config_filenames(config_paths):
     '''
     Given a sequence of config paths, both filenames and directories, resolve that to just an
     iterable of files. Accomplish this by listing any given directories looking for contained config
-    files. This is non-recursive, so any directories within the given directories are ignored.
+    files (ending with the ".yaml" extension). This is non-recursive, so any directories within the
+    given directories are ignored.
 
     Return paths even if they don't exist on disk, so the user can find out about missing
     configuration paths. However, skip a default config path if it's missing, so the user doesn't
     have to create a default config path unless they need it.
     '''
-    real_default_config_paths = set(map(os.path.realpath, DEFAULT_CONFIG_PATHS))
+    real_default_config_paths = set(map(os.path.realpath, get_default_config_paths()))
 
     for path in config_paths:
         exists = os.path.exists(path)
@@ -28,5 +43,5 @@ def collect_config_filenames(config_paths):
 
         for filename in os.listdir(path):
             full_filename = os.path.join(path, filename)
-            if not os.path.isdir(full_filename):
+            if full_filename.endswith('.yaml') and not os.path.isdir(full_filename):
                 yield full_filename

borgmatic/config/schema.yaml

@@ -22,6 +22,10 @@ map:
                 type: bool
                 desc: Stay in same file system (do not cross mount points).
                 example: true
+            bsd_flags:
+                type: bool
+                desc: Record bsdflags (e.g. NODUMP, IMMUTABLE) in archive. Defaults to true.
+                example: true
             files_cache:
                 type: scalar
                 desc: |
@@ -43,7 +47,8 @@ map:
                     - type: scalar
                 desc: |
                     Paths to local or remote repositories (required). Tildes are expanded. Multiple
-                    repositories are backed up to in sequence.
+                    repositories are backed up to in sequence. See ssh_command for SSH options like
+                    identity file or port.
                 example:
                     - user@backupserver:sourcehostname.borg
             patterns:
@@ -51,9 +56,9 @@ map:
                     - type: scalar
                 desc: |
                     Any paths matching these patterns are included/excluded from backups. Globs are
-                    expanded. Note that Borg considers this option experimental. See the output of
-                    "borg help patterns" for more details. Quoting any value if it contains leading
-                    punctuation, so it parses correctly.
+                    expanded. (Tildes are not.) Note that Borg considers this option experimental.
+                    See the output of "borg help patterns" for more details. Quote any value if it
+                    contains leading punctuation, so it parses correctly.
                 example:
                     - 'R /'
                     - '- /home/*/.cache'
@@ -72,11 +77,11 @@ map:
                 seq:
                     - type: scalar
                 desc: |
-                    Any paths matching these patterns are excluded from backups. Globs are expanded.
-                    See the output of "borg help patterns" for more details.
+                    Any paths matching these patterns are excluded from backups. Globs and tildes
+                    are expanded. See the output of "borg help patterns" for more details.
                 example:
                     - '*.pyc'
-                    - /home/*/.cache
+                    - ~/*/.cache
                     - /etc/ssl
             exclude_from:
                 seq:
@@ -103,6 +108,14 @@ map:
             https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables for
             details.
         map:
+            encryption_passcommand:
+                type: scalar
+                desc: |
+                    The standard output of this command is used to unlock the encryption key. Only
+                    use on repositories that were initialized with passcommand/repokey encryption.
+                    Note that if both encryption_passcommand and encryption_passphrase are set,
+                    then encryption_passphrase takes precedence.
+                example: "secret-tool lookup borg-repository repo-name"
             encryption_passphrase:
                 type: scalar
                 desc: |
@@ -130,6 +143,10 @@ map:
                 type: scalar
                 desc: Umask to be used for borg create.
                 example: 0077
+            lock_wait:
+                type: int
+                desc: Maximum seconds to wait for acquiring a repository/cache lock.
+                example: 5
             archive_name_format:
                 type: scalar
                 desc: |
@@ -137,12 +154,14 @@ map:
                     "borg help placeholders" for details. Default is
                     "{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}". If you specify this option, you must
                     also specify a prefix in the retention section to avoid accidental pruning of
-                    archives with a different archive name format.
+                    archives with a different archive name format. And you should also specify a
+                    prefix in the consistency section as well.
                 example: "{hostname}-documents-{now}"
     retention:
         desc: |
             Retention policy for how many backups to keep in each category. See
             https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for details.
+            At least one of the "keep" options is required for pruning to work.
         map:
             keep_within:
                 type: scalar
@@ -204,6 +223,13 @@ map:
                 desc: Restrict the number of checked archives to the last n. Applies only to the
                       "archives" check.
                 example: 3
+            prefix:
+                type: scalar
+                desc: |
+                    When performing the "archives" check, only consider archive names starting with
+                    this prefix. Borg placeholders can be used. See the output of
+                    "borg help placeholders" for details. Default is "{hostname}-".
+                example: sourcehostname
     hooks:
         desc: |
             Shell commands or scripts to execute before and after a backup or if an error has occurred.

borgmatic/config/validate.py

@@ -8,6 +8,9 @@ import pykwalify.errors
 from ruamel import yaml
 
 
+logger = logging.getLogger(__name__)
+
+
 def schema_filename():
     '''
     Path to the installed YAML configuration schema file, used to validate and parse the
@@ -50,6 +53,11 @@ def apply_logical_validation(config_filename, parsed_configuration):
             )
         )
 
+    consistency_prefix = parsed_configuration.get('consistency', {}).get('prefix')
+    if archive_name_format and not consistency_prefix:
+        logger.warning('Since version 1.1.16, if you provide `archive_name_format`, you should also'
+                       ' specify `consistency.prefix`.')
+
 
 def parse_configuration(config_filename, schema_filename):
     '''

borgmatic/tests/integration/commands/test_borgmatic.py

@@ -7,14 +7,20 @@ from borgmatic.commands import borgmatic as module
 
 
 def test_parse_arguments_with_no_arguments_uses_defaults():
+    config_paths = ['default']
+    flexmock(module.collect).should_receive('get_default_config_paths').and_return(config_paths)
+
     parser = module.parse_arguments()
 
-    assert parser.config_paths == module.collect.DEFAULT_CONFIG_PATHS
+    assert parser.config_paths == config_paths
     assert parser.excludes_filename == None
     assert parser.verbosity is None
+    assert parser.json is False
 
 
 def test_parse_arguments_with_path_arguments_overrides_defaults():
+    flexmock(module.collect).should_receive('get_default_config_paths').and_return(['default'])
+
     parser = module.parse_arguments('--config', 'myconfig', '--excludes', 'myexcludes')
 
     assert parser.config_paths == ['myconfig']
@@ -23,6 +29,8 @@ def test_parse_arguments_with_path_arguments_overrides_defaults():
 
 
 def test_parse_arguments_with_multiple_config_paths_parses_as_list():
+    flexmock(module.collect).should_receive('get_default_config_paths').and_return(['default'])
+
     parser = module.parse_arguments('--config', 'myconfig', 'otherconfig')
 
     assert parser.config_paths == ['myconfig', 'otherconfig']
@@ -30,14 +38,24 @@ def test_parse_arguments_with_multiple_config_paths_parses_as_list():
 
 
 def test_parse_arguments_with_verbosity_flag_overrides_default():
+    config_paths = ['default']
+    flexmock(module.collect).should_receive('get_default_config_paths').and_return(config_paths)
+
     parser = module.parse_arguments('--verbosity', '1')
 
-    assert parser.config_paths == module.collect.DEFAULT_CONFIG_PATHS
+    assert parser.config_paths == config_paths
     assert parser.excludes_filename == None
     assert parser.verbosity == 1
 
 
+def test_parse_arguments_with_json_flag_overrides_default():
+    parser = module.parse_arguments('--list', '--json')
+    assert parser.json is True
+
+
 def test_parse_arguments_with_no_actions_defaults_to_all_actions_enabled():
+    flexmock(module.collect).should_receive('get_default_config_paths').and_return(['default'])
+
     parser = module.parse_arguments()
 
     assert parser.prune is True
@@ -46,6 +64,8 @@ def test_parse_arguments_with_no_actions_defaults_to_all_actions_enabled():
 
 
 def test_parse_arguments_with_prune_action_leaves_other_actions_disabled():
+    flexmock(module.collect).should_receive('get_default_config_paths').and_return(['default'])
+
     parser = module.parse_arguments('--prune')
 
     assert parser.prune is True
@@ -54,6 +74,8 @@ def test_parse_arguments_with_prune_action_leaves_other_actions_disabled():
 
 
 def test_parse_arguments_with_multiple_actions_leaves_other_action_disabled():
+    flexmock(module.collect).should_receive('get_default_config_paths').and_return(['default'])
+
     parser = module.parse_arguments('--create', '--check')
 
     assert parser.prune is False
@@ -62,5 +84,22 @@ def test_parse_arguments_with_multiple_actions_leaves_other_action_disabled():
 
 
 def test_parse_arguments_with_invalid_arguments_exits():
+    flexmock(module.collect).should_receive('get_default_config_paths').and_return(['default'])
+
     with pytest.raises(SystemExit):
         module.parse_arguments('--posix-me-harder')
+
+
+def test_parse_arguments_with_json_flag_with_list_or_info_flag_does_not_raise_any_error():
+    module.parse_arguments('--list', '--json')
+    module.parse_arguments('--info', '--json')
+
+
+def test_parse_arguments_with_json_flag_but_no_list_or_info_flag_raises_value_error():
+    with pytest.raises(ValueError):
+        module.parse_arguments('--json')
+
+
+def test_parse_arguments_with_json_flag_and_both_list_and_info_flag_raises_value_error():
+    with pytest.raises(ValueError):
+        module.parse_arguments('--list', '--info', '--json')

borgmatic/tests/unit/borg/test_check.py

@@ -42,40 +42,64 @@ def test_parse_checks_with_disabled_returns_no_checks():
     assert checks == ()
 
 
-def test_make_check_flags_with_checks_returns_flags():
+def test_make_check_flags_with_repository_check_returns_flag():
     flags = module._make_check_flags(('repository',))
 
     assert flags == ('--repository-only',)
 
 
-def test_make_check_flags_with_extract_check_does_not_make_extract_flag():
+def test_make_check_flags_with_extract_omits_extract_flag():
     flags = module._make_check_flags(('extract',))
 
     assert flags == ()
 
 
-def test_make_check_flags_with_default_checks_returns_no_flags():
+def test_make_check_flags_with_default_checks_returns_default_flags():
     flags = module._make_check_flags(module.DEFAULT_CHECKS)
 
-    assert flags == ()
+    assert flags == ('--prefix', module.DEFAULT_PREFIX)
 
 
-def test_make_check_flags_with_all_checks_returns_no_flags():
+def test_make_check_flags_with_all_checks_returns_default_flags():
     flags = module._make_check_flags(module.DEFAULT_CHECKS + ('extract',))
 
-    assert flags == ()
+    assert flags == ('--prefix', module.DEFAULT_PREFIX)
 
 
-def test_make_check_flags_with_checks_and_last_returns_flags_including_last():
+def test_make_check_flags_with_archives_check_and_last_includes_last_flag():
+    flags = module._make_check_flags(('archives',), check_last=3)
+
+    assert flags == ('--archives-only', '--last', '3', '--prefix', module.DEFAULT_PREFIX)
+
+
+def test_make_check_flags_with_repository_check_and_last_omits_last_flag():
     flags = module._make_check_flags(('repository',), check_last=3)
 
-    assert flags == ('--repository-only', '--last', '3')
+    assert flags == ('--repository-only',)
 
 
-def test_make_check_flags_with_default_checks_and_last_returns_last_flag():
+def test_make_check_flags_with_default_checks_and_last_includes_last_flag():
     flags = module._make_check_flags(module.DEFAULT_CHECKS, check_last=3)
 
-    assert flags == ('--last', '3')
+    assert flags == ('--last', '3', '--prefix', module.DEFAULT_PREFIX)
+
+
+def test_make_check_flags_with_archives_check_and_prefix_includes_prefix_flag():
+    flags = module._make_check_flags(('archives',), prefix='foo-')
+
+    assert flags == ('--archives-only', '--prefix', 'foo-')
+
+
+def test_make_check_flags_with_repository_check_and_prefix_omits_prefix_flag():
+    flags = module._make_check_flags(('repository',), prefix='foo-')
+
+    assert flags == ('--repository-only',)
+
+
+def test_make_check_flags_with_default_checks_and_prefix_includes_prefix_flag():
+    flags = module._make_check_flags(module.DEFAULT_CHECKS, prefix='foo-')
+
+    assert flags == ('--prefix', 'foo-')
 
 
 @pytest.mark.parametrize(
@@ -89,9 +113,9 @@ def test_make_check_flags_with_default_checks_and_last_returns_last_flag():
 )
 def test_check_archives_calls_borg_with_parameters(checks):
     check_last = flexmock()
-    consistency_config = flexmock().should_receive('get').and_return(check_last).mock
+    consistency_config = {'check_last': check_last}
     flexmock(module).should_receive('_parse_checks').and_return(checks)
-    flexmock(module).should_receive('_make_check_flags').with_args(checks, check_last).and_return(())
+    flexmock(module).should_receive('_make_check_flags').with_args(checks, check_last, None).and_return(())
     stdout = flexmock()
     insert_subprocess_mock(
         ('borg', 'check', 'repo'),
@@ -103,6 +127,7 @@ def test_check_archives_calls_borg_with_parameters(checks):
     module.check_archives(
         verbosity=None,
         repository='repo',
+        storage_config={},
         consistency_config=consistency_config,
     )
 
@@ -110,7 +135,7 @@ def test_check_archives_calls_borg_with_parameters(checks):
 def test_check_archives_with_extract_check_calls_extract_only():
     checks = ('extract',)
     check_last = flexmock()
-    consistency_config = flexmock().should_receive('get').and_return(check_last).mock
+    consistency_config = {'check_last': check_last}
     flexmock(module).should_receive('_parse_checks').and_return(checks)
     flexmock(module).should_receive('_make_check_flags').never()
     flexmock(module.extract).should_receive('extract_last_archive_dry_run').once()
@@ -119,13 +144,14 @@ def test_check_archives_with_extract_check_calls_extract_only():
     module.check_archives(
         verbosity=None,
         repository='repo',
+        storage_config={},
         consistency_config=consistency_config,
     )
 
 
 def test_check_archives_with_verbosity_some_calls_borg_with_info_parameter():
     checks = ('repository',)
-    consistency_config = flexmock().should_receive('get').and_return(None).mock
+    consistency_config = {'check_last': None}
     flexmock(module).should_receive('_parse_checks').and_return(checks)
     flexmock(module).should_receive('_make_check_flags').and_return(())
     insert_subprocess_mock(
@@ -136,13 +162,14 @@ def test_check_archives_with_verbosity_some_calls_borg_with_info_parameter():
     module.check_archives(
         verbosity=VERBOSITY_SOME,
         repository='repo',
+        storage_config={},
         consistency_config=consistency_config,
     )
 
 
 def test_check_archives_with_verbosity_lots_calls_borg_with_debug_parameter():
     checks = ('repository',)
-    consistency_config = flexmock().should_receive('get').and_return(None).mock
+    consistency_config = {'check_last': None}
     flexmock(module).should_receive('_parse_checks').and_return(checks)
     flexmock(module).should_receive('_make_check_flags').and_return(())
     insert_subprocess_mock(
@@ -153,18 +180,20 @@ def test_check_archives_with_verbosity_lots_calls_borg_with_debug_parameter():
     module.check_archives(
         verbosity=VERBOSITY_LOTS,
         repository='repo',
+        storage_config={},
         consistency_config=consistency_config,
     )
 
 
 def test_check_archives_without_any_checks_bails():
-    consistency_config = flexmock().should_receive('get').and_return(None).mock
+    consistency_config = {'check_last': None}
     flexmock(module).should_receive('_parse_checks').and_return(())
     insert_subprocess_never()
 
     module.check_archives(
         verbosity=None,
         repository='repo',
+        storage_config={},
         consistency_config=consistency_config,
     )
 
@@ -172,9 +201,9 @@ def test_check_archives_without_any_checks_bails():
 def test_check_archives_with_local_path_calls_borg_via_local_path():
     checks = ('repository',)
     check_last = flexmock()
-    consistency_config = flexmock().should_receive('get').and_return(check_last).mock
+    consistency_config = {'check_last': check_last}
     flexmock(module).should_receive('_parse_checks').and_return(checks)
-    flexmock(module).should_receive('_make_check_flags').with_args(checks, check_last).and_return(())
+    flexmock(module).should_receive('_make_check_flags').with_args(checks, check_last, None).and_return(())
     stdout = flexmock()
     insert_subprocess_mock(
         ('borg1', 'check', 'repo'),
@@ -186,6 +215,7 @@ def test_check_archives_with_local_path_calls_borg_via_local_path():
     module.check_archives(
         verbosity=None,
         repository='repo',
+        storage_config={},
         consistency_config=consistency_config,
         local_path='borg1',
     )
@@ -194,9 +224,9 @@ def test_check_archives_with_local_path_calls_borg_via_local_path():
 def test_check_archives_with_remote_path_calls_borg_with_remote_path_parameters():
     checks = ('repository',)
     check_last = flexmock()
-    consistency_config = flexmock().should_receive('get').and_return(check_last).mock
+    consistency_config = {'check_last': check_last}
     flexmock(module).should_receive('_parse_checks').and_return(checks)
-    flexmock(module).should_receive('_make_check_flags').with_args(checks, check_last).and_return(())
+    flexmock(module).should_receive('_make_check_flags').with_args(checks, check_last, None).and_return(())
     stdout = flexmock()
     insert_subprocess_mock(
         ('borg', 'check', 'repo', '--remote-path', 'borg1'),
@@ -208,6 +238,53 @@ def test_check_archives_with_remote_path_calls_borg_with_remote_path_parameters(
     module.check_archives(
         verbosity=None,
         repository='repo',
+        storage_config={},
         consistency_config=consistency_config,
         remote_path='borg1',
     )
+
+
+def test_check_archives_with_lock_wait_calls_borg_with_lock_wait_parameters():
+    checks = ('repository',)
+    check_last = flexmock()
+    consistency_config = {'check_last': check_last}
+    flexmock(module).should_receive('_parse_checks').and_return(checks)
+    flexmock(module).should_receive('_make_check_flags').with_args(checks, check_last, None).and_return(())
+    stdout = flexmock()
+    insert_subprocess_mock(
+        ('borg', 'check', 'repo', '--lock-wait', '5'),
+        stdout=stdout, stderr=STDOUT,
+    )
+    flexmock(sys.modules['builtins']).should_receive('open').and_return(stdout)
+    flexmock(module.os).should_receive('devnull')
+
+    module.check_archives(
+        verbosity=None,
+        repository='repo',
+        storage_config={'lock_wait': 5},
+        consistency_config=consistency_config,
+    )
+
+
+def test_check_archives_with_retention_prefix():
+    checks = ('repository',)
+    check_last = flexmock()
+    prefix = 'foo-'
+    consistency_config = {'check_last': check_last, 'prefix': prefix}
+    flexmock(module).should_receive('_parse_checks').and_return(checks)
+    flexmock(module).should_receive('_make_check_flags').with_args(checks, check_last, prefix).and_return(())
+    stdout = flexmock()
+    insert_subprocess_mock(
+        ('borg', 'check', 'repo'),
+        stdout=stdout, stderr=STDOUT,
+    )
+
+    flexmock(sys.modules['builtins']).should_receive('open').and_return(stdout)
+    flexmock(module.os).should_receive('devnull')
+
+    module.check_archives(
+        verbosity=None,
+        repository='repo',
+        storage_config={},
+        consistency_config=consistency_config,
+    )

borgmatic/tests/unit/borg/test_create.py

@@ -6,6 +6,17 @@ from borgmatic.borg import create as module
 from borgmatic.verbosity import VERBOSITY_SOME, VERBOSITY_LOTS
 
 
+def test_initialize_environment_with_passcommand_should_set_environment():
+    orig_environ = os.environ
+
+    try:
+        os.environ = {}
+        module.initialize_environment({'encryption_passcommand': 'command'})
+        assert os.environ.get('BORG_PASSCOMMAND') == 'command'
+    finally:
+        os.environ = orig_environ
+
+
 def test_initialize_environment_with_passphrase_should_set_environment():
     orig_environ = os.environ
 
@@ -34,6 +45,7 @@ def test_initialize_environment_without_configuration_should_not_set_environment
     try:
         os.environ = {}
         module.initialize_environment({})
+        assert os.environ.get('BORG_PASSCOMMAND') == None
         assert os.environ.get('BORG_PASSPHRASE') == None
         assert os.environ.get('BORG_RSH') == None
     finally:
@@ -58,6 +70,21 @@ def test_expand_directory_with_glob_expands():
     assert paths == ['foo', 'food']
 
 
+def test_expand_directories_flattens_expanded_directories():
+    flexmock(module).should_receive('_expand_directory').with_args('~/foo').and_return(['/root/foo'])
+    flexmock(module).should_receive('_expand_directory').with_args('bar*').and_return(['bar', 'barf'])
+
+    paths = module._expand_directories(('~/foo', 'bar*'))
+
+    assert paths == ('/root/foo', 'bar', 'barf')
+
+
+def test_expand_directories_considers_none_as_no_directories():
+    paths = module._expand_directories(None)
+
+    assert paths == ()
+
+
 def test_write_pattern_file_does_not_raise():
     temporary_file = flexmock(
         name='filename',
@@ -84,7 +111,7 @@ def test_make_pattern_flags_includes_pattern_filename_when_given():
         pattern_filename='/tmp/patterns',
     )
 
-    assert pattern_flags == ('--pattern-from', '/tmp/patterns')
+    assert pattern_flags == ('--patterns-from', '/tmp/patterns')
 
 
 def test_make_pattern_flags_includes_patterns_from_filenames_when_in_config():
@@ -92,7 +119,7 @@ def test_make_pattern_flags_includes_patterns_from_filenames_when_in_config():
         location_config={'patterns_from': ['patterns', 'other']},
     )
 
-    assert pattern_flags == ('--pattern-from', 'patterns', '--pattern-from', 'other')
+    assert pattern_flags == ('--patterns-from', 'patterns', '--patterns-from', 'other')
 
 
 def test_make_pattern_flags_includes_both_filenames_when_patterns_given_and_patterns_from_in_config():
@@ -101,7 +128,7 @@ def test_make_pattern_flags_includes_both_filenames_when_patterns_given_and_patt
         pattern_filename='/tmp/patterns',
     )
 
-    assert pattern_flags == ('--pattern-from', 'patterns', '--pattern-from', '/tmp/patterns')
+    assert pattern_flags == ('--patterns-from', 'patterns', '--patterns-from', '/tmp/patterns')
 
 
 def test_make_pattern_flags_considers_none_patterns_from_filenames_as_empty():
@@ -182,7 +209,7 @@ CREATE_COMMAND = ('borg', 'create', 'repo::{}'.format(DEFAULT_ARCHIVE_NAME), 'fo
 
 
 def test_create_archive_calls_borg_with_parameters():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo']).and_return(['bar'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -190,6 +217,7 @@ def test_create_archive_calls_borg_with_parameters():
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo', 'bar'],
@@ -202,7 +230,7 @@ def test_create_archive_calls_borg_with_parameters():
 
 def test_create_archive_with_patterns_calls_borg_with_patterns():
     pattern_flags = ('--patterns-from', 'patterns')
-    flexmock(module).should_receive('_expand_directory').and_return(['foo']).and_return(['bar'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(flexmock(name='/tmp/patterns')).and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(pattern_flags)
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -210,6 +238,7 @@ def test_create_archive_with_patterns_calls_borg_with_patterns():
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo', 'bar'],
@@ -222,7 +251,7 @@ def test_create_archive_with_patterns_calls_borg_with_patterns():
 
 def test_create_archive_with_exclude_patterns_calls_borg_with_excludes():
     exclude_flags = ('--exclude-from', 'excludes')
-    flexmock(module).should_receive('_expand_directory').and_return(['foo']).and_return(['bar'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(('exclude',))
     flexmock(module).should_receive('_write_pattern_file').and_return(None).and_return(flexmock(name='/tmp/excludes'))
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(exclude_flags)
@@ -230,6 +259,7 @@ def test_create_archive_with_exclude_patterns_calls_borg_with_excludes():
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo', 'bar'],
@@ -241,7 +271,7 @@ def test_create_archive_with_exclude_patterns_calls_borg_with_excludes():
 
 
 def test_create_archive_with_verbosity_some_calls_borg_with_info_parameter():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo']).and_return(['bar'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
@@ -250,6 +280,7 @@ def test_create_archive_with_verbosity_some_calls_borg_with_info_parameter():
 
     module.create_archive(
         verbosity=VERBOSITY_SOME,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo', 'bar'],
@@ -261,7 +292,7 @@ def test_create_archive_with_verbosity_some_calls_borg_with_info_parameter():
 
 
 def test_create_archive_with_verbosity_lots_calls_borg_with_debug_parameter():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo']).and_return(['bar'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -269,6 +300,70 @@ def test_create_archive_with_verbosity_lots_calls_borg_with_debug_parameter():
 
     module.create_archive(
         verbosity=VERBOSITY_LOTS,
+        dry_run=False,
+        repository='repo',
+        location_config={
+            'source_directories': ['foo', 'bar'],
+            'repositories': ['repo'],
+            'exclude_patterns': None,
+        },
+        storage_config={},
+    )
+
+
+def test_create_archive_with_dry_run_calls_borg_with_dry_run_parameter():
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
+    flexmock(module).should_receive('_write_pattern_file').and_return(None)
+    flexmock(module).should_receive('_make_pattern_flags').and_return(())
+    flexmock(module).should_receive('_make_pattern_flags').and_return(())
+    flexmock(module).should_receive('_make_exclude_flags').and_return(())
+    insert_subprocess_mock(CREATE_COMMAND + ('--dry-run',))
+
+    module.create_archive(
+        verbosity=None,
+        dry_run=True,
+        repository='repo',
+        location_config={
+            'source_directories': ['foo', 'bar'],
+            'repositories': ['repo'],
+            'exclude_patterns': None,
+        },
+        storage_config={},
+    )
+
+
+def test_create_archive_with_dry_run_and_verbosity_some_calls_borg_without_stats_parameter():
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
+    flexmock(module).should_receive('_write_pattern_file').and_return(None)
+    flexmock(module).should_receive('_make_pattern_flags').and_return(())
+    flexmock(module).should_receive('_make_pattern_flags').and_return(())
+    flexmock(module).should_receive('_make_exclude_flags').and_return(())
+    insert_subprocess_mock(CREATE_COMMAND + ('--info', '--dry-run'))
+
+    module.create_archive(
+        verbosity=VERBOSITY_SOME,
+        dry_run=True,
+        repository='repo',
+        location_config={
+            'source_directories': ['foo', 'bar'],
+            'repositories': ['repo'],
+            'exclude_patterns': None,
+        },
+        storage_config={},
+    )
+
+
+def test_create_archive_with_dry_run_and_verbosity_lots_calls_borg_without_stats_parameter():
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
+    flexmock(module).should_receive('_write_pattern_file').and_return(None)
+    flexmock(module).should_receive('_make_pattern_flags').and_return(())
+    flexmock(module).should_receive('_make_pattern_flags').and_return(())
+    flexmock(module).should_receive('_make_exclude_flags').and_return(())
+    insert_subprocess_mock(CREATE_COMMAND + ('--debug', '--list', '--dry-run'))
+
+    module.create_archive(
+        verbosity=VERBOSITY_LOTS,
+        dry_run=True,
         repository='repo',
         location_config={
             'source_directories': ['foo', 'bar'],
@@ -280,7 +375,7 @@ def test_create_archive_with_verbosity_lots_calls_borg_with_debug_parameter():
 
 
 def test_create_archive_with_compression_calls_borg_with_compression_parameters():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo']).and_return(['bar'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -288,6 +383,7 @@ def test_create_archive_with_compression_calls_borg_with_compression_parameters(
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo', 'bar'],
@@ -299,7 +395,7 @@ def test_create_archive_with_compression_calls_borg_with_compression_parameters(
 
 
 def test_create_archive_with_remote_rate_limit_calls_borg_with_remote_ratelimit_parameters():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo']).and_return(['bar'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -307,6 +403,7 @@ def test_create_archive_with_remote_rate_limit_calls_borg_with_remote_ratelimit_
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo', 'bar'],
@@ -318,7 +415,7 @@ def test_create_archive_with_remote_rate_limit_calls_borg_with_remote_ratelimit_
 
 
 def test_create_archive_with_one_file_system_calls_borg_with_one_file_system_parameters():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo']).and_return(['bar'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -326,6 +423,7 @@ def test_create_archive_with_one_file_system_calls_borg_with_one_file_system_par
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo', 'bar'],
@@ -337,8 +435,50 @@ def test_create_archive_with_one_file_system_calls_borg_with_one_file_system_par
     )
 
 
+def test_create_archive_with_bsd_flags_true_calls_borg_without_nobsdflags_parameter():
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
+    flexmock(module).should_receive('_write_pattern_file').and_return(None)
+    flexmock(module).should_receive('_make_pattern_flags').and_return(())
+    flexmock(module).should_receive('_make_exclude_flags').and_return(())
+    insert_subprocess_mock(CREATE_COMMAND)
+
+    module.create_archive(
+        verbosity=None,
+        dry_run=False,
+        repository='repo',
+        location_config={
+            'source_directories': ['foo', 'bar'],
+            'repositories': ['repo'],
+            'bsd_flags': True,
+            'exclude_patterns': None,
+        },
+        storage_config={},
+    )
+
+
+def test_create_archive_with_bsd_flags_false_calls_borg_with_nobsdflags_parameter():
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
+    flexmock(module).should_receive('_write_pattern_file').and_return(None)
+    flexmock(module).should_receive('_make_pattern_flags').and_return(())
+    flexmock(module).should_receive('_make_exclude_flags').and_return(())
+    insert_subprocess_mock(CREATE_COMMAND + ('--nobsdflags',))
+
+    module.create_archive(
+        verbosity=None,
+        dry_run=False,
+        repository='repo',
+        location_config={
+            'source_directories': ['foo', 'bar'],
+            'repositories': ['repo'],
+            'bsd_flags': False,
+            'exclude_patterns': None,
+        },
+        storage_config={},
+    )
+
+
 def test_create_archive_with_files_cache_calls_borg_with_files_cache_parameters():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo']).and_return(['bar'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -346,6 +486,7 @@ def test_create_archive_with_files_cache_calls_borg_with_files_cache_parameters(
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo', 'bar'],
@@ -358,7 +499,7 @@ def test_create_archive_with_files_cache_calls_borg_with_files_cache_parameters(
 
 
 def test_create_archive_with_local_path_calls_borg_via_local_path():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo']).and_return(['bar'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -366,6 +507,7 @@ def test_create_archive_with_local_path_calls_borg_via_local_path():
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo', 'bar'],
@@ -378,7 +520,7 @@ def test_create_archive_with_local_path_calls_borg_via_local_path():
 
 
 def test_create_archive_with_remote_path_calls_borg_with_remote_path_parameters():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo']).and_return(['bar'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -386,6 +528,7 @@ def test_create_archive_with_remote_path_calls_borg_with_remote_path_parameters(
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo', 'bar'],
@@ -398,7 +541,7 @@ def test_create_archive_with_remote_path_calls_borg_with_remote_path_parameters(
 
 
 def test_create_archive_with_umask_calls_borg_with_umask_parameters():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo']).and_return(['bar'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -406,6 +549,7 @@ def test_create_archive_with_umask_calls_borg_with_umask_parameters():
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo', 'bar'],
@@ -416,8 +560,28 @@ def test_create_archive_with_umask_calls_borg_with_umask_parameters():
     )
 
 
+def test_create_archive_with_lock_wait_calls_borg_with_lock_wait_parameters():
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
+    flexmock(module).should_receive('_write_pattern_file').and_return(None)
+    flexmock(module).should_receive('_make_pattern_flags').and_return(())
+    flexmock(module).should_receive('_make_exclude_flags').and_return(())
+    insert_subprocess_mock(CREATE_COMMAND + ('--lock-wait', '5'))
+
+    module.create_archive(
+        verbosity=None,
+        dry_run=False,
+        repository='repo',
+        location_config={
+            'source_directories': ['foo', 'bar'],
+            'repositories': ['repo'],
+            'exclude_patterns': None,
+        },
+        storage_config={'lock_wait': 5},
+    )
+
+
 def test_create_archive_with_source_directories_glob_expands():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo', 'food'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'food')).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -426,6 +590,7 @@ def test_create_archive_with_source_directories_glob_expands():
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo*'],
@@ -437,7 +602,7 @@ def test_create_archive_with_source_directories_glob_expands():
 
 
 def test_create_archive_with_non_matching_source_directories_glob_passes_through():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo*'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo*',)).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -446,6 +611,7 @@ def test_create_archive_with_non_matching_source_directories_glob_passes_through
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo*'],
@@ -457,7 +623,7 @@ def test_create_archive_with_non_matching_source_directories_glob_passes_through
 
 
 def test_create_archive_with_glob_calls_borg_with_expanded_directories():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo', 'food'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'food')).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -465,6 +631,7 @@ def test_create_archive_with_glob_calls_borg_with_expanded_directories():
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo*'],
@@ -476,7 +643,7 @@ def test_create_archive_with_glob_calls_borg_with_expanded_directories():
 
 
 def test_create_archive_with_archive_name_format_calls_borg_with_archive_name():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo']).and_return(['bar'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return(())
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -484,6 +651,7 @@ def test_create_archive_with_archive_name_format_calls_borg_with_archive_name():
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo', 'bar'],
@@ -497,7 +665,7 @@ def test_create_archive_with_archive_name_format_calls_borg_with_archive_name():
 
 
 def test_create_archive_with_archive_name_format_accepts_borg_placeholders():
-    flexmock(module).should_receive('_expand_directory').and_return(['foo']).and_return(['bar'])
+    flexmock(module).should_receive('_expand_directories').and_return(('foo', 'bar')).and_return([])
     flexmock(module).should_receive('_write_pattern_file').and_return(None)
     flexmock(module).should_receive('_make_pattern_flags').and_return(())
     flexmock(module).should_receive('_make_exclude_flags').and_return(())
@@ -505,6 +673,7 @@ def test_create_archive_with_archive_name_format_accepts_borg_placeholders():
 
     module.create_archive(
         verbosity=None,
+        dry_run=False,
         repository='repo',
         location_config={
             'source_directories': ['foo', 'bar'],

borgmatic/tests/unit/borg/test_extract.py

@@ -34,6 +34,7 @@ def test_extract_last_archive_dry_run_should_call_borg_with_last_archive():
     module.extract_last_archive_dry_run(
         verbosity=None,
         repository='repo',
+        lock_wait=None,
     )
 
 
@@ -48,6 +49,7 @@ def test_extract_last_archive_dry_run_without_any_archives_should_bail():
     module.extract_last_archive_dry_run(
         verbosity=None,
         repository='repo',
+        lock_wait=None,
     )
 
 
@@ -64,6 +66,7 @@ def test_extract_last_archive_dry_run_with_verbosity_some_should_call_borg_with_
     module.extract_last_archive_dry_run(
         verbosity=VERBOSITY_SOME,
         repository='repo',
+        lock_wait=None,
     )
 
 
@@ -80,6 +83,7 @@ def test_extract_last_archive_dry_run_with_verbosity_lots_should_call_borg_with_
     module.extract_last_archive_dry_run(
         verbosity=VERBOSITY_LOTS,
         repository='repo',
+        lock_wait=None,
     )
 
 
@@ -96,6 +100,7 @@ def test_extract_last_archive_dry_run_should_call_borg_via_local_path():
     module.extract_last_archive_dry_run(
         verbosity=None,
         repository='repo',
+        lock_wait=None,
         local_path='borg1',
     )
 
@@ -113,5 +118,23 @@ def test_extract_last_archive_dry_run_should_call_borg_with_remote_path_paramete
     module.extract_last_archive_dry_run(
         verbosity=None,
         repository='repo',
+        lock_wait=None,
         remote_path='borg1',
     )
+
+
+def test_extract_last_archive_dry_run_should_call_borg_with_lock_wait_parameters():
+    flexmock(sys.stdout).encoding = 'utf-8'
+    insert_subprocess_check_output_mock(
+        ('borg', 'list', '--short', 'repo', '--lock-wait', '5'),
+        result='archive1\narchive2\n'.encode('utf-8'),
+    )
+    insert_subprocess_mock(
+        ('borg', 'extract', '--dry-run', 'repo::archive2', '--lock-wait', '5'),
+    )
+
+    module.extract_last_archive_dry_run(
+        verbosity=None,
+        repository='repo',
+        lock_wait=5,
+    )

borgmatic/tests/unit/borg/test_info.py

@@ -0,0 +1,88 @@
+from collections import OrderedDict
+
+from flexmock import flexmock
+
+from borgmatic.borg import info as module
+from borgmatic.verbosity import VERBOSITY_SOME, VERBOSITY_LOTS
+
+
+def insert_subprocess_mock(check_call_command, **kwargs):
+    subprocess = flexmock(module.subprocess)
+    subprocess.should_receive('check_output').with_args(check_call_command, **kwargs).once()
+
+
+INFO_COMMAND = ('borg', 'info', 'repo')
+
+
+def test_display_archives_info_calls_borg_with_parameters():
+    insert_subprocess_mock(INFO_COMMAND)
+
+    module.display_archives_info(
+        verbosity=None,
+        repository='repo',
+        storage_config={},
+    )
+
+
+def test_display_archives_info_with_verbosity_some_calls_borg_with_info_parameter():
+    insert_subprocess_mock(INFO_COMMAND + ('--info',))
+
+    module.display_archives_info(
+        repository='repo',
+        storage_config={},
+        verbosity=VERBOSITY_SOME,
+    )
+
+
+def test_display_archives_info_with_verbosity_lots_calls_borg_with_debug_parameter():
+    insert_subprocess_mock(INFO_COMMAND + ('--debug',))
+
+    module.display_archives_info(
+        repository='repo',
+        storage_config={},
+        verbosity=VERBOSITY_LOTS,
+    )
+
+
+def test_display_archives_info_with_json_calls_borg_with_json_parameter():
+    insert_subprocess_mock(INFO_COMMAND + ('--json',))
+
+    module.display_archives_info(
+        verbosity=None,
+        repository='repo',
+        storage_config={},
+        json=True,
+    )
+
+
+def test_display_archives_info_with_local_path_calls_borg_via_local_path():
+    insert_subprocess_mock(('borg1',) + INFO_COMMAND[1:])
+
+    module.display_archives_info(
+        verbosity=None,
+        repository='repo',
+        storage_config={},
+        local_path='borg1',
+    )
+
+
+def test_display_archives_info_with_remote_path_calls_borg_with_remote_path_parameters():
+    insert_subprocess_mock(INFO_COMMAND + ('--remote-path', 'borg1'))
+
+    module.display_archives_info(
+        verbosity=None,
+        repository='repo',
+        storage_config={},
+        remote_path='borg1',
+    )
+
+
+def test_display_archives_info_with_lock_wait_calls_borg_with_lock_wait_parameters():
+    storage_config = {'lock_wait': 5}
+    insert_subprocess_mock(INFO_COMMAND + ('--lock-wait', '5'))
+
+    module.display_archives_info(
+        verbosity=None,
+        repository='repo',
+        storage_config=storage_config,
+    )

borgmatic/tests/unit/borg/test_list.py

@@ -0,0 +1,88 @@
+from collections import OrderedDict
+
+from flexmock import flexmock
+
+from borgmatic.borg import list as module
+from borgmatic.verbosity import VERBOSITY_SOME, VERBOSITY_LOTS
+
+
+def insert_subprocess_mock(check_call_command, **kwargs):
+    subprocess = flexmock(module.subprocess)
+    subprocess.should_receive('check_output').with_args(check_call_command, **kwargs).once()
+
+
+LIST_COMMAND = ('borg', 'list', 'repo')
+
+
+def test_list_archives_calls_borg_with_parameters():
+    insert_subprocess_mock(LIST_COMMAND)
+
+    module.list_archives(
+        verbosity=None,
+        repository='repo',
+        storage_config={},
+    )
+
+
+def test_list_archives_with_verbosity_some_calls_borg_with_info_parameter():
+    insert_subprocess_mock(LIST_COMMAND + ('--info',))
+
+    module.list_archives(
+        repository='repo',
+        storage_config={},
+        verbosity=VERBOSITY_SOME,
+    )
+
+
+def test_list_archives_with_verbosity_lots_calls_borg_with_debug_parameter():
+    insert_subprocess_mock(LIST_COMMAND + ('--debug',))
+
+    module.list_archives(
+        repository='repo',
+        storage_config={},
+        verbosity=VERBOSITY_LOTS,
+    )
+
+
+def test_list_archives_with_json_calls_borg_with_json_parameter():
+    insert_subprocess_mock(LIST_COMMAND + ('--json',))
+
+    module.list_archives(
+        verbosity=None,
+        repository='repo',
+        storage_config={},
+        json=True,
+    )
+
+
+def test_list_archives_with_local_path_calls_borg_via_local_path():
+    insert_subprocess_mock(('borg1',) + LIST_COMMAND[1:])
+
+    module.list_archives(
+        verbosity=None,
+        repository='repo',
+        storage_config={},
+        local_path='borg1',
+    )
+
+
+def test_list_archives_with_remote_path_calls_borg_with_remote_path_parameters():
+    insert_subprocess_mock(LIST_COMMAND + ('--remote-path', 'borg1'))
+
+    module.list_archives(
+        verbosity=None,
+        repository='repo',
+        storage_config={},
+        remote_path='borg1',
+    )
+
+
+def test_list_archives_with_lock_wait_calls_borg_with_lock_wait_parameters():
+    storage_config = {'lock_wait': 5}
+    insert_subprocess_mock(LIST_COMMAND + ('--lock-wait', '5'))
+
+    module.list_archives(
+        verbosity=None,
+        repository='repo',
+        storage_config=storage_config,
+    )

borgmatic/tests/unit/borg/test_prune.py

@@ -64,7 +64,9 @@ def test_prune_archives_calls_borg_with_parameters():
 
     module.prune_archives(
         verbosity=None,
+        dry_run=False,
         repository='repo',
+        storage_config={},
         retention_config=retention_config,
     )
 
@@ -78,7 +80,9 @@ def test_prune_archives_with_verbosity_some_calls_borg_with_info_parameter():
 
     module.prune_archives(
         repository='repo',
+        storage_config={},
         verbosity=VERBOSITY_SOME,
+        dry_run=False,
         retention_config=retention_config,
     )
 
@@ -92,7 +96,25 @@ def test_prune_archives_with_verbosity_lots_calls_borg_with_debug_parameter():
 
     module.prune_archives(
         repository='repo',
+        storage_config={},
         verbosity=VERBOSITY_LOTS,
+        dry_run=False,
+        retention_config=retention_config,
+    )
+
+
+def test_prune_archives_with_dry_run_calls_borg_with_dry_run_parameter():
+    retention_config = flexmock()
+    flexmock(module).should_receive('_make_prune_flags').with_args(retention_config).and_return(
+        BASE_PRUNE_FLAGS,
+    )
+    insert_subprocess_mock(PRUNE_COMMAND + ('--dry-run',))
+
+    module.prune_archives(
+        repository='repo',
+        storage_config={},
+        verbosity=None,
+        dry_run=True,
         retention_config=retention_config,
     )
 
@@ -106,7 +128,9 @@ def test_prune_archives_with_local_path_calls_borg_via_local_path():
 
     module.prune_archives(
         verbosity=None,
+        dry_run=False,
         repository='repo',
+        storage_config={},
         retention_config=retention_config,
         local_path='borg1',
     )
@@ -121,7 +145,43 @@ def test_prune_archives_with_remote_path_calls_borg_with_remote_path_parameters(
 
     module.prune_archives(
         verbosity=None,
+        dry_run=False,
         repository='repo',
+        storage_config={},
         retention_config=retention_config,
         remote_path='borg1',
     )
+
+
+def test_prune_archives_with_umask_calls_borg_with_umask_parameters():
+    storage_config = {'umask': '077'}
+    retention_config = flexmock()
+    flexmock(module).should_receive('_make_prune_flags').with_args(retention_config).and_return(
+        BASE_PRUNE_FLAGS,
+    )
+    insert_subprocess_mock(PRUNE_COMMAND + ('--umask', '077'))
+
+    module.prune_archives(
+        verbosity=None,
+        dry_run=False,
+        repository='repo',
+        storage_config=storage_config,
+        retention_config=retention_config,
+    )
+
+
+def test_prune_archives_with_lock_wait_calls_borg_with_lock_wait_parameters():
+    storage_config = {'lock_wait': 5}
+    retention_config = flexmock()
+    flexmock(module).should_receive('_make_prune_flags').with_args(retention_config).and_return(
+        BASE_PRUNE_FLAGS,
+    )
+    insert_subprocess_mock(PRUNE_COMMAND + ('--lock-wait', '5'))
+
+    module.prune_archives(
+        verbosity=None,
+        dry_run=False,
+        repository='repo',
+        storage_config=storage_config,
+        retention_config=retention_config,
+    )

borgmatic/tests/unit/commands/test_borgmatic.py

@@ -0,0 +1,52 @@
+import json
+import sys
+
+from flexmock import flexmock
+import pytest
+
+from borgmatic.commands import borgmatic
+
+
+def test__run_commands_handles_multiple_json_outputs_in_array():
+    (
+        flexmock(borgmatic)
+        .should_receive('_run_commands_on_repository')
+        .times(3)
+        .replace_with(
+            lambda args, consistency, json_results, local_path, location, remote_path, retention,
+            storage,
+            unexpanded_repository: json_results.append({"whatever": unexpanded_repository})
+        )
+    )
+
+    (
+        flexmock(sys.stdout)
+        .should_call("write")
+        .with_args(
+            json.dumps(
+                json.loads(
+                    '''
+                        [
+                            {"whatever": "fake_repo1"},
+                            {"whatever": "fake_repo2"},
+                            {"whatever": "fake_repo3"}
+                        ]
+                    ''',
+                )
+            )
+        )
+    )
+
+    borgmatic._run_commands(
+        args=flexmock(json=True),
+        consistency=None,
+        local_path=None,
+        location={'repositories': [
+            'fake_repo1',
+            'fake_repo2',
+            'fake_repo3'
+        ]},
+        remote_path=None,
+        retention=None,
+        storage=None,
+    )

borgmatic/tests/unit/config/test_collect.py

@@ -3,6 +3,22 @@ from flexmock import flexmock
 from borgmatic.config import collect as module
 
 
+def test_get_default_config_paths_includes_absolute_user_config_path():
+    flexmock(module.os, environ={'XDG_CONFIG_HOME': None, 'HOME': '/home/user'})
+
+    config_paths = module.get_default_config_paths()
+
+    assert '/home/user/.config/borgmatic/config.yaml' in config_paths
+
+
+def test_get_default_config_paths_prefers_xdg_config_home_for_user_config_path():
+    flexmock(module.os, environ={'XDG_CONFIG_HOME': '/home/user/.etc', 'HOME': '/home/user'})
+
+    config_paths = module.get_default_config_paths()
+
+    assert '/home/user/.etc/borgmatic/config.yaml' in config_paths
+
+
 def test_collect_config_filenames_collects_given_files():
     config_paths = ('config.yaml', 'other.yaml')
     flexmock(module.os.path).should_receive('isdir').and_return(False)
@@ -32,6 +48,21 @@ def test_collect_config_filenames_collects_files_from_given_directories_and_igno
     )
 
 
+def test_collect_config_filenames_collects_files_from_given_directories_and_ignores_non_yaml_filenames():
+    config_paths = ('/etc/borgmatic.d',)
+    mock_path = flexmock(module.os.path)
+    mock_path.should_receive('exists').and_return(True)
+    mock_path.should_receive('isdir').with_args('/etc/borgmatic.d').and_return(True)
+    mock_path.should_receive('isdir').with_args('/etc/borgmatic.d/foo.yaml').and_return(False)
+    mock_path.should_receive('isdir').with_args('/etc/borgmatic.d/bar.yaml~').and_return(False)
+    mock_path.should_receive('isdir').with_args('/etc/borgmatic.d/baz.txt').and_return(False)
+    flexmock(module.os).should_receive('listdir').and_return(['foo.yaml', 'bar.yaml~', 'baz.txt'])
+
+    config_filenames = tuple(module.collect_config_filenames(config_paths))
+
+    assert config_filenames == ('/etc/borgmatic.d/foo.yaml',)
+
+
 def test_collect_config_filenames_skips_etc_borgmatic_config_dot_yaml_if_it_does_not_exist():
     config_paths = ('config.yaml', '/etc/borgmatic/config.yaml')
     mock_path = flexmock(module.os.path)

borgmatic/tests/unit/config/test_validate.py

@@ -1,4 +1,5 @@
 import pytest
+from flexmock import flexmock
 
 from borgmatic.config import validate as module
 
@@ -23,13 +24,42 @@ def test_apply_logical_validation_raises_if_archive_name_format_present_without_
             },
         )
 
+def test_apply_logical_validation_raises_if_archive_name_format_present_without_retention_prefix():
+    with pytest.raises(module.Validation_error):
+        module.apply_logical_validation(
+            'config.yaml',
+            {
+                'storage': {'archive_name_format': '{hostname}-{now}'},
+                'retention': {'keep_daily': 7},
+                'consistency': {'prefix': '{hostname}-'}
+            },
+        )
+
+
+def test_apply_logical_validation_warns_if_archive_name_format_present_without_consistency_prefix():
+    logger = flexmock(module.logger)
+    logger.should_receive('warning').once()
 
-def test_apply_logical_validation_does_not_raise_if_archive_name_format_and_prefix_present():
     module.apply_logical_validation(
         'config.yaml',
         {
             'storage': {'archive_name_format': '{hostname}-{now}'},
             'retention': {'prefix': '{hostname}-'},
+            'consistency': {},
+        },
+    )
+
+
+def test_apply_logical_validation_does_not_raise_or_warn_if_archive_name_format_and_prefix_present():
+    logger = flexmock(module.logger)
+    logger.should_receive('warning').never()
+
+    module.apply_logical_validation(
+        'config.yaml',
+        {
+            'storage': {'archive_name_format': '{hostname}-{now}'},
+            'retention': {'prefix': '{hostname}-'},
+            'consistency': {'prefix': '{hostname}-'}
         },
     )
 

borgmatic/tests/unit/test_verbosity.py

@@ -7,5 +7,5 @@ def test_verbosity_to_log_level_maps_known_verbosity_to_log_level():
     assert module.verbosity_to_log_level(module.VERBOSITY_SOME) == logging.INFO
 
 
-def test_verbosity_to_log_level_maps_unknown_verbosity_to_error_level():
-    assert module.verbosity_to_log_level('my pants') == logging.ERROR
+def test_verbosity_to_log_level_maps_unknown_verbosity_to_warning_level():
+    assert module.verbosity_to_log_level('my pants') == logging.WARNING

borgmatic/verbosity.py

@@ -12,4 +12,4 @@ def verbosity_to_log_level(verbosity):
     return {
         VERBOSITY_SOME: logging.INFO,
         VERBOSITY_LOTS: logging.DEBUG,
-    }.get(verbosity, logging.ERROR)
+    }.get(verbosity, logging.WARNING)

sample/systemd/borgmatic.timer

@@ -3,6 +3,7 @@ Description=Run borgmatic backup
 
 [Timer]
 OnCalendar=daily
+Persistent=true
 
 [Install]
 WantedBy=timers.target

scripts/find-unsupported-borg-options

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+set -o nounset
+
 # For each Borg sub-command that borgmatic uses, print out the Borg flags that borgmatic does not
 # appear to support yet. This script isn't terribly robust. It's intended as a basic tool to ferret
 # out unsupported Borg options so that they can be considered for addition to borgmatic.
@@ -11,10 +13,10 @@ generate-borgmatic-config --destination temp.yaml
 # from running borgmatic with the generated configuration. Then, collect the full set of available
 # Borg flags as reported by "borg --help" for that sub-command. Finally, compare the two lists of
 # flags to determine which Borg flags borgmatic doesn't yet support.
-for sub_command in prune create check; do
+for sub_command in prune create check list info; do
     echo "********** borg $sub_command **********"
 
-    for line in $(borgmatic --config temp.yaml --$sub_command -v 2 2>&1 | grep "borg $sub_command") ; do
+    for line in $(borgmatic --config temp.yaml --$sub_command -v 2 2>&1 | grep "borg\w* $sub_command") ; do
         echo "$line" | grep '^-' >> borgmatic_borg_flags
     done
     sort borgmatic_borg_flags > borgmatic_borg_flags.sorted

scripts/push

@@ -2,5 +2,5 @@
 
 set -e
 
-git push -u origin
-git push -u github
+git push -u origin master
+git push -u github master

scripts/release

@@ -2,6 +2,11 @@
 
 set -e
 
+version=$(head --lines=1 NEWS)
+git tag $version
+git push origin $version
+git push github $version
+
 rm -fr dist
 python3 setup.py bdist_wheel
 python3 setup.py sdist

setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup, find_packages
 
 
-VERSION = '1.1.13'
+VERSION = '1.2.1'
 
 
 setup(
@@ -33,7 +33,7 @@ setup(
     ],
     install_requires=(
         'pykwalify>=1.6.0',
-        'ruamel.yaml<=0.15',
+        'ruamel.yaml>0.15.0,<0.16.0',
         'setuptools',
     ),
     tests_require=(

test_requirements.txt

@@ -1,5 +1,5 @@
 flexmock==0.10.2
-pykwalify==1.6.0
-pytest==2.9.1
+pykwalify==1.6.1
+pytest==3.6.3
 pytest-cov==2.5.1
-ruamel.yaml==0.15.18
+ruamel.yaml>0.15.0,<0.16.0

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist=py34
+envlist=py3
 skipsdist=True
 
 [testenv]