Add support for Borg 1.2 ...

- add compact command
- add chunker_params, sparse, sparse, threshold, upload_ratelimit, and upload_buffer settings.

doc/configuring.rst

@@ -1155,6 +1155,14 @@ append_only
 Create an append-only mode repository.
 
 
+.. _chunker_params:
+
+chunker_params
+~~~~~~~~~~~~~~
+
+Parameters used by the chunker command.
+
+
 .. _compression:
 
 compression
@@ -1345,13 +1353,38 @@ remote_path
 Name of *Borg* executable on remote platform.
 
 
+.. _sparse:
+
+sparse
+~~~~~~~~~
+
+Detect sparse holes in input (supported only by fixed chunker).
+
+Requires *Borg* version 1.2 or newer.
+
+
+.. _threshold:
+
+threshold
+~~~~~~~~~
+
+Sets minimum threshold for saved space when compacting a repository with the 
+:ref:`compact command <compact>`.  Value is given in percent.
+
+Requires *Borg* version 1.2 or newer.
+
+
 .. _remote_ratelimit:
 
 remote_ratelimit
 ~~~~~~~~~~~~~~~~
 
 Set remote network upload rate limit in KiB/s (default: 0=unlimited).
 
+*Borg* has deprecated *remote_ratelimit* in version 1.2.  If you are seeing this 
+warning, you should rename *remote_ratelimit* to *upload_ratelimit* in your 
+*Emborg* settings file.
+
 
 .. _umask:
 
@@ -1362,6 +1395,27 @@ Set umask. This is passed to *Borg*. It uses it when creating files, either
 local or remote. The default is 0o077.
 
 
+.. _upload_buffer:
+
+upload_buffer
+~~~~~~~~~~~~~
+
+Set network upload buffer size in MiB.  By default no buffer is used.  Requires 
+*Borg* version 1.2 or newer.
+
+
+.. _upload_ratelimit:
+
+upload_ratelimit
+~~~~~~~~~~~~~~~~
+
+Set upload rate limit in KiB/s when writing to a remote network (default: 
+0=unlimited).
+
+Use *upload_ratelimit* when using *Borg* version 1.2 or higher, otherwise use 
+*remote_ratelimit*.
+
+
 .. _working_dir:
 
 working_dir

doc/releases.rst

@@ -6,6 +6,15 @@ Latest development release
 | Version: 1.30.2
 | Released: 2022-02-15
 
+- Enhanced *Emborg* to support new Borg 1.2 features.
+  - Added :ref:`compact command <compact>`
+  - Added
+    :ref:`chunker_params`,
+    :ref:`sparse`,
+    :ref:`sparse`,
+    :ref:`threshold`,
+    :ref:`upload_ratelimit`,
+    :ref:`upload_buffer` settings.
 - Added the :ref:`run_before_borg and run_after_borg <run_before_borg>` 
   settings.
 - Added the ``--cache-only`` option and the ability to delete multiple archives 

emborg/command.py

@@ -287,7 +287,7 @@ def help(cls):
 # BorgCommand command {{{1
 class BorgCommand(Command):
     NAMES = "borg".split()
-    DESCRIPTION = "run a raw borg command."
+    DESCRIPTION = "run a raw borg command"
     USAGE = dedent(
         """
         Usage:
@@ -317,7 +317,7 @@ def run(cls, command, args, settings, options):
 # BreakLockCommand command {{{1
 class BreakLockCommand(Command):
     NAMES = "breaklock break-lock".split()
-    DESCRIPTION = "breaks the repository and cache locks."
+    DESCRIPTION = "breaks the repository and cache locks"
     USAGE = dedent(
         """
         Usage:
@@ -405,6 +405,55 @@ def run(cls, command, args, settings, options):
         return borg.status
 
 
+# CompactCommand command {{{1
+class CompactCommand(Command):
+    NAMES = "compact".split()
+    DESCRIPTION = "compact segment files in the repository"
+    USAGE = dedent(
+        """
+        Usage:
+            emborg compact [options]
+
+        Options:
+            -p, --progress        shows Borg progress
+
+        This command frees repository space by compacting segments.
+
+        Use this regularly to avoid running out of space, however you do not
+        need to it after each after each Borg command. It is especially useful
+        after deleting archives, because only compaction will really free
+        repository space.
+
+        Requires Borg version 1.2 or newer.
+        """
+    ).strip()
+    REQUIRES_EXCLUSIVITY = True
+    COMPOSITE_CONFIGS = "all"
+    LOG_COMMAND = True
+
+    @classmethod
+    def run(cls, command, args, settings, options):
+        # read command line
+        cmdline = docopt(cls.USAGE, argv=[command] + args)
+        borg_opts = []
+        if cmdline["--progress"] or settings.show_progress:
+            borg_opts.append("--progress")
+
+        # run borg
+        borg = settings.run_borg(
+            cmd = "compact",
+            borg_opts = borg_opts,
+            args = [settings.destination()],
+            emborg_opts = options,
+            show_borg_output = bool(borg_opts),
+        )
+        out = borg.stdout
+        if out:
+            output(out.rstrip())
+
+        return borg.status
+
+
 # CompareCommand command {{{1
 class CompareCommand(Command):
     NAMES = "compare".split()
@@ -699,6 +748,7 @@ def run(cls, command, args, settings, options):
             else:
                 check_status = 0
 
+            # prune the repository if requested
             activity = "pruning"
             if settings.prune_after_create:
                 announce("Pruning archives ...")
@@ -727,6 +777,7 @@ class DeleteCommand(Command):
             emborg delete [options] [<archive>...]
 
         Options:
+            -f, --fast     skip compacting
             -r, --repo     delete entire repository
             -s, --stats    show Borg statistics
             --cache-only   delete only the local cache for the given repository
@@ -772,8 +823,29 @@ def run(cls, command, args, settings, options):
         out = borg.stdout
         if out:
             output(out.rstrip())
+        delete_status = borg.status
 
-        return borg.status
+        if cmdline["--fast"]:
+            return delete_status
+
+        try:
+            # compact the repository if requested
+            if settings.compact_after_delete:
+                narrate("Compacting repository ...")
+                compact = CompactCommand()
+                compact_status = compact.run("compact", args, settings, options)
+            else:
+                compact_status = 0
+
+        except Error as e:
+            e.reraise(
+                codicil = (
+                    f"This error occurred while compacting the repository.",
+                    "No error was reported while deleting the archive.",
+                )
+            )
+
+        return max([delete_status, compact_status])
 
 
 # DiffCommand command {{{1
@@ -1643,6 +1715,7 @@ class PruneCommand(Command):
         Options:
             -e, --include-external   prune all archives in repository, not just
                                      those associated with this configuration
+            -f, --fast               skip compacting
             -l, --list               show fate of each archive
             -s, --stats              show Borg statistics
         """
@@ -1661,6 +1734,7 @@ def run(cls, command, args, settings, options):
             borg_opts.append("--stats")
         if cmdline["--list"]:
             borg_opts.append("--list")
+        fast = cmdline["--fast"]
 
         # checking the settings
         intervals = "within last minutely hourly daily weekly monthly yearly"
@@ -1685,8 +1759,29 @@ def run(cls, command, args, settings, options):
         out = borg.stdout
         if out:
             output(out.rstrip())
+        prune_status = borg.status
 
-        return borg.status
+        if cmdline["--fast"]:
+            return prune_status
+
+        try:
+            # compact the repository if requested
+            if settings.compact_after_delete:
+                narrate("Compacting repository ...")
+                compact = CompactCommand()
+                compact_status = compact.run("compact", args, settings, options)
+            else:
+                compact_status = 0
+
+        except Error as e:
+            e.reraise(
+                codicil = (
+                    f"This error occurred while compacting the repository.",
+                    "No error was reported while pruning the repository.",
+                )
+            )
+
+        return max([prune_status, compact_status])
 
 
 # RestoreCommand command {{{1
@@ -1776,15 +1871,19 @@ def run(cls, command, args, settings, options):
 # SettingsCommand command {{{1
 class SettingsCommand(Command):
     NAMES = "settings setting".split()
-    DESCRIPTION = "list settings of chosen configuration"
+    DESCRIPTION = "display settings of chosen configuration"
     USAGE = dedent(
         """
         Usage:
             emborg settings [options] [<name>]
             emborg setting [options] [<name>]
 
         Options:
-            -a, --available   list available settings
+            -a, --available   list available settings and give their
+                              descriptions rather than their values
+
+        If given without an argument all specified settings of a config are
+        listed and their values displayed.
         """
     ).strip()
     REQUIRES_EXCLUSIVITY = False