Context tweaks + mention configuration upgrade in command hook documentation (#1019).

borgmatic/commands/borgmatic.py

@@ -103,7 +103,7 @@ def run_configuration(config_filename, config, config_paths, arguments):
         dry_run=global_arguments.dry_run,
         action_names=arguments.keys(),
         configuration_filename=config_filename,
-        log_file=arguments['global'].log_file,
+        log_file=arguments['global'].log_file or '',
     ):
         try:
             local_borg_version = borg_version.local_borg_version(config, local_path)
@@ -243,7 +243,7 @@ def run_configuration(config_filename, config, config_paths, arguments):
                 config.get('umask'),
                 global_arguments.dry_run,
                 configuration_filename=config_filename,
-                log_file=arguments['global'].log_file,
+                log_file=arguments['global'].log_file or '',
                 repository=error_repository.get('path', '') if error_repository else '',
                 repository_label=error_repository.get('label', '') if error_repository else '',
                 error=encountered_error,
@@ -834,7 +834,7 @@ def collect_configuration_run_summary_logs(configs, config_paths, arguments):
                 config.get('umask'),
                 arguments['global'].dry_run,
                 configuration_filename=config_filename,
-                log_file=arguments['global'].log_file,
+                log_file=arguments['global'].log_file or '',
             )
     except (CalledProcessError, ValueError, OSError) as error:
         yield from log_error_records('Error running before everything hook', error)
@@ -896,7 +896,7 @@ def collect_configuration_run_summary_logs(configs, config_paths, arguments):
                 config.get('umask'),
                 arguments['global'].dry_run,
                 configuration_filename=config_filename,
-                log_file=arguments['global'].log_file,
+                log_file=arguments['global'].log_file or '',
             )
     except (CalledProcessError, ValueError, OSError) as error:
         yield from log_error_records('Error running after everything hook', error)

docs/how-to/add-preparation-and-cleanup-steps-to-backups.md

@@ -38,8 +38,13 @@ commands:
           - echo "Something went wrong!"
 ```
 
-If a `run:` command contains a special YAML character such as a colon, you may
-need to quote the entire string (or use a [multiline
+If you're coming from an older version of borgmatic, there is tooling to help
+you [upgrade your
+configuration](https://torsion.org/borgmatic/docs/how-to/upgrade/#upgrading-your-configuration)
+to this new command hook format.
+
+Note that if a `run:` command contains a special YAML character such as a colon,
+you may need to quote the entire string (or use a [multiline
 string](https://yaml-multiline.info/)) to avoid an error:
 
 ```yaml
@@ -61,8 +66,8 @@ Each command in the `commands:` list has the following options:
  * `when`: Only trigger the hook when borgmatic is run with particular actions (`create`, `prune`, etc.) listed here. Defaults to running for all actions.
  * `run`: List of one or more shell commands or scripts to run when this command hook is triggered.
 
-Note that borgmatic does not run `error` hooks if an error occurs within an
-`everything` hook.
+borgmatic does not run `error` hooks if an error occurs within an `everything`
+hook.
 
 There's also another command hook that works a little differently: