NEWS

@@ -1,4 +1,8 @@
-1.4.21.dev0
+1.4.22.dev0
+ * #276: Disable colored output when "--json" flag is used, so as to produce valid JSON ouput.
+ * In "borgmatic --help", don't expand $HOME in listing of default "--config" paths.
+
+1.4.21
  * #268: Override particular configuration options from the command-line via "--override" flag. See
    the documentation for more information:
    https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/#configuration-overrides

borgmatic/commands/arguments.py

@@ -107,7 +107,8 @@ def parse_arguments(*unparsed_arguments):
     Given command-line arguments with which this script was invoked, parse the arguments and return
     them as a dict mapping from subparser name (or "global") to an argparse.Namespace instance.
     '''
-    config_paths = collect.get_default_config_paths()
+    config_paths = collect.get_default_config_paths(expand_home=True)
+    unexpanded_config_paths = collect.get_default_config_paths(expand_home=False)
 
     global_parser = ArgumentParser(add_help=False)
     global_group = global_parser.add_argument_group('global arguments')
@@ -119,7 +120,7 @@ def parse_arguments(*unparsed_arguments):
         dest='config_paths',
         default=config_paths,
         help='Configuration filenames or directories, defaults to: {}'.format(
-            ' '.join(config_paths)
+            ' '.join(unexpanded_config_paths)
         ),
     )
     global_group.add_argument(

borgmatic/commands/borgmatic.py

@@ -625,7 +625,13 @@ def main():  # pragma: no cover
     config_filenames = tuple(collect.collect_config_filenames(global_arguments.config_paths))
     configs, parse_logs = load_configurations(config_filenames, global_arguments.overrides)
 
-    colorama.init(autoreset=True, strip=not should_do_markup(global_arguments.no_color, configs))
+    any_json_flags = any(
+        getattr(sub_arguments, 'json', False) for sub_arguments in arguments.values()
+    )
+    colorama.init(
+        autoreset=True,
+        strip=not should_do_markup(global_arguments.no_color or any_json_flags, configs),
+    )
     try:
         configure_logging(
             verbosity_to_log_level(global_arguments.verbosity),

borgmatic/config/collect.py

@@ -1,15 +1,17 @@
 import os
 
 
-def get_default_config_paths():
+def get_default_config_paths(expand_home=True):
     '''
     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.
+
+    Don't expand the home directory ($HOME) if the expand home flag is False.
     '''
-    user_config_directory = os.getenv('XDG_CONFIG_HOME') or os.path.expandvars(
-        os.path.join('$HOME', '.config')
-    )
+    user_config_directory = os.getenv('XDG_CONFIG_HOME') or os.path.join('$HOME', '.config')
+    if expand_home:
+        user_config_directory = os.path.expandvars(user_config_directory)
 
     return [
         '/etc/borgmatic/config.yaml',

docs/how-to/inspect-your-backups.md

@@ -95,7 +95,8 @@ borgmatic --log-file /path/to/file.log
 ```
 
 Note that if you use the `--log-file` flag, you are responsible for rotating
-the log file so it doesn't grow too large. Also, there is a
+the log file so it doesn't grow too large, for example with
+[logrotate](https://wiki.archlinux.org/index.php/Logrotate). Also, there is a
 `--log-file-verbosity` flag to customize the log file's log level.
 
 

docs/how-to/set-up-backups.md

@@ -204,8 +204,7 @@ Then, from the directory where you downloaded them:
 
 ```bash
 sudo mv borgmatic.service borgmatic.timer /etc/systemd/system/
-sudo systemctl enable borgmatic.timer
-sudo systemctl start borgmatic.timer
+sudo systemctl enable --now borgmatic.timer
 ```
 
 Feel free to modify the timer file based on how frequently you'd like
@@ -214,10 +213,10 @@ borgmatic to run.
 ## Colored output
 
 Borgmatic produces colored terminal output by default. It is disabled when a
-non-interactive terminal is detected (like a cron job). Otherwise, you can
-disable it by passing the `--no-color` flag, setting the environment variable
-`PY_COLORS=False`, or setting the `color` option to `false` in the `output`
-section of configuration.
+non-interactive terminal is detected (like a cron job), or when you use the
+`--json` flag. Otherwise, you can disable it by passing the `--no-color` flag,
+setting the environment variable `PY_COLORS=False`, or setting the `color`
+option to `false` in the `output` section of configuration.
 
 ## Troubleshooting
 

sample/systemd/borgmatic.service

@@ -15,8 +15,10 @@ IOSchedulingPriority=7
 IOWeight=100
 
 Restart=no
+# Prevent rate limiting of borgmatic log events. If you are using an older version of systemd that
+# doesn't support this (pre-240 or so), you may have to remove this option.
 LogRateLimitIntervalSec=0
 
 # Delay start to prevent backups running during boot.
-ExecStartPre=sleep 1m
-ExecStart=systemd-inhibit --who="borgmatic" --why="Prevent interrupting scheduled backup" /root/.local/bin/borgmatic --syslog-verbosity 1
+ExecStartPre=/usr/bin/sleep 1m
+ExecStart=/usr/bin/systemd-inhibit --who="borgmatic" --why="Prevent interrupting scheduled backup" /root/.local/bin/borgmatic --syslog-verbosity 1

setup.py

@@ -1,6 +1,6 @@
 from setuptools import find_packages, setup
 
-VERSION = '1.4.21.dev0'
+VERSION = '1.4.22.dev0'
 
 
 setup(

tests/unit/config/test_collect.py

@@ -21,6 +21,14 @@ def test_get_default_config_paths_prefers_xdg_config_home_for_user_config_path()
     assert '/home/user/.etc/borgmatic/config.yaml' in config_paths
 
 
+def test_get_default_config_paths_does_not_expand_home_when_false():
+    flexmock(module.os, environ={'HOME': '/home/user'})
+
+    config_paths = module.get_default_config_paths(expand_home=False)
+
+    assert '$HOME/.config/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)