Fix changelog development version.

NEWS

@@ -1,3 +1,7 @@
+1.7.3.dev0
+ * #587: Warn when ignoring a configured "read_special" value of false, as true is needed when
+   database hooks are enabled.
+
 1.7.2
  * #577: Fix regression in which "borgmatic info --archive ..." showed repository info instead of
    archive info with Borg 1.

borgmatic/borg/create.py

@@ -295,6 +295,11 @@ def create_archive(
 
     ensure_files_readable(location_config.get('patterns_from'), location_config.get('exclude_from'))
 
+    if stream_processes and location_config.get('read_special') is False:
+        logger.warning(
+            f'{repository}: Ignoring configured "read_special" value of false, as true is needed for database hooks.'
+        )
+
     full_command = (
         tuple(local_path.split(' '))
         + ('create',)

docs/how-to/backup-your-databases.md

@@ -215,8 +215,9 @@ databases that share the exact same name on different hosts.
 setting to support dump and restore streaming, you'll need to ensure that any
 special files are excluded from backups (named pipes, block devices,
 character devices, and sockets) to prevent hanging. Try a command like
-`find /your/source/path -type c,b,p,s` to find such files. Common directories
-to exclude are `/dev` and `/run`, but that may not be exhaustive.
+`find /your/source/path -type b -or -type c -or -type p -or -type s` to find
+such files. Common directories to exclude are `/dev` and `/run`, but that may
+not be exhaustive.
 
 
 ### Manual restoration

docs/how-to/run-arbitrary-borg-commands.md

@@ -30,8 +30,8 @@ based on your borgmatic configuration files or command-line arguments:
 
 ### borg action
 
-The way you run Borg with borgmatic is via the `borg` action. Here's a simple
-example:
+<span class="minilink minilink-addedin">New in version 1.5.15</span> The way
+you run Borg with borgmatic is via the `borg` action. Here's a simple example:
 
 ```bash
 borgmatic borg break-lock
@@ -87,6 +87,9 @@ borgmatic's `borg` action is not without limitations:
    borgmatic action. In this case, only the Borg command is run.
  * Unlike normal borgmatic actions that support JSON, the `borg` action will
    not disable certain borgmatic logs to avoid interfering with JSON output.
+ * Unlike other borgmatic actions, the `borg` action captures (and logs) all
+   output, so interactive prompts or flags like `--progress` will not work as
+   expected.
 
 In general, this `borgmatic borg` feature should be considered an escape
 valve—a feature of second resort. In the long run, it's preferable to wrap

setup.py

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

tests/unit/borg/test_create.py

@@ -1673,6 +1673,50 @@ def test_create_archive_with_progress_and_stream_processes_calls_borg_with_progr
     )
 
 
+def test_create_archive_with_stream_processes_ignores_read_special_false_logs_warning():
+    processes = flexmock()
+    flexmock(module).should_receive('borgmatic_source_directories').and_return([])
+    flexmock(module).should_receive('deduplicate_directories').and_return(('foo', 'bar'))
+    flexmock(module).should_receive('map_directories_to_devices').and_return({})
+    flexmock(module).should_receive('expand_directories').and_return(())
+    flexmock(module).should_receive('pattern_root_directories').and_return([])
+    flexmock(module.os.path).should_receive('expanduser').and_raise(TypeError)
+    flexmock(module).should_receive('expand_home_directories').and_return(())
+    flexmock(module).should_receive('write_pattern_file').and_return(None)
+    flexmock(module.feature).should_receive('available').and_return(True)
+    flexmock(module).should_receive('ensure_files_readable')
+    flexmock(module.logger).should_receive('warning').once()
+    flexmock(module).should_receive('make_pattern_flags').and_return(())
+    flexmock(module).should_receive('make_exclude_flags').and_return(())
+    flexmock(module.flags).should_receive('make_repository_archive_flags').and_return(
+        (f'repo::{DEFAULT_ARCHIVE_NAME}',)
+    )
+    flexmock(module.environment).should_receive('make_environment')
+    flexmock(module).should_receive('execute_command_with_processes').with_args(
+        ('borg', 'create', '--one-file-system', '--read-special') + REPO_ARCHIVE_WITH_PATHS,
+        processes=processes,
+        output_log_level=logging.INFO,
+        output_file=None,
+        borg_local_path='borg',
+        working_directory=None,
+        extra_environment=None,
+    )
+
+    module.create_archive(
+        dry_run=False,
+        repository='repo',
+        location_config={
+            'source_directories': ['foo', 'bar'],
+            'repositories': ['repo'],
+            'exclude_patterns': None,
+            'read_special': False,
+        },
+        storage_config={},
+        local_borg_version='1.2.3',
+        stream_processes=processes,
+    )
+
+
 def test_create_archive_with_json_calls_borg_with_json_parameter():
     flexmock(module).should_receive('borgmatic_source_directories').and_return([])
     flexmock(module).should_receive('deduplicate_directories').and_return(('foo', 'bar'))