diff --sort-by: enhanced sorting, fixes #8998

use borg diff --sort-by=spec1,spec2,spec2 for enhanced sorting.

keep legacy --sort behaviour (sort by path) for compatibility,
but deprecate it.

Co-authored-by: Daniel Rudolf <[email protected]>

This is a port of #9005 to master branch.

Author: ThomasWaldmann

docs/usage/diff.rst

@@ -16,3 +16,11 @@ Examples
     {"path": "file4", "changes": [{"type": "added", "size": 0}]}
     {"path": "file3", "changes": [{"type": "removed", "size": 0}]}
 
+
+    # Use --sort-by with a comma-separated list; sorts apply stably from last to first.
+    # Here: primary by net size change descending, tie-breaker by path ascending
+    $ borg diff --sort-by=">size_diff,path" archive1 archive2
+        +17 B      -5 B [-rw-r--r-- -> -rwxr-xr-x] file1
+    removed         0 B file3
+    added           0 B file4
+       +135 B    -252 B file2

src/borg/archiver/__init__.py

@@ -177,6 +177,7 @@ def print_file_status(self, status, path):
     def preprocess_args(self, args):
         deprecations = [
             # ('--old', '--new' or None, 'Warning: "--old" has been deprecated. Use "--new" instead.'),
+            ("--sort", None, 'Warning: "--sort" is deprecated. Use "--sort-by=path" instead.')
         ]
         for i, arg in enumerate(args[:]):
             for old_name, new_name, warning in deprecations:

src/borg/archiver/diff_cmd.py

@@ -7,7 +7,15 @@
 from ._common import with_repository, build_matcher, Highlander
 from ..archive import Archive
 from ..constants import *  # NOQA
-from ..helpers import BaseFormatter, DiffFormatter, archivename_validator, PathSpec, BorgJsonEncoder
+from ..helpers import (
+    BaseFormatter,
+    DiffFormatter,
+    archivename_validator,
+    PathSpec,
+    BorgJsonEncoder,
+    IncludePatternNeverMatchedWarning,
+    remove_surrogates,
+)
 from ..manifest import Manifest
 from ..logger import create_logger
 
@@ -87,11 +95,81 @@ def print_text_output(diff, formatter):
         diffs_iter = Archive.compare_archives_iter(
             archive1, archive2, matcher, can_compare_chunk_ids=can_compare_chunk_ids
         )
-        # Conversion to string and filtering for diff.equal to save memory if sorting
+        # Filter out equal items early (keep as generator; listify only if sorting)
         diffs = (diff for diff in diffs_iter if not diff.equal(args.content_only))
 
-        if args.sort:
-            diffs = sorted(diffs, key=lambda diff: diff.path)
+        # Enhanced sorting support: --sort-by takes precedence; legacy --sort sorts by path
+        sort_specs = []
+        if getattr(args, "sort_by", None):
+            # Comma-separated list
+            for spec in str(args.sort_by).split(","):
+                spec = spec.strip()
+                if spec:
+                    sort_specs.append(spec)
+        elif getattr(args, "sort", False):
+            sort_specs = ["path"]
+
+        def key_for(field: str, d: "ItemDiff"):
+            # strip direction markers if present
+            if field and field[0] in ("<", ">"):
+                field = field[1:]
+            # path
+            if field in (None, "", "path"):
+                return remove_surrogates(d.path)
+            # compute size_* from changes
+            if field in ("size_diff", "size_added", "size_removed"):
+                added = removed = 0
+                ch = d.changes().get("content")
+                if ch is not None:
+                    info = ch.to_dict()
+                    t = info.get("type")
+                    if t == "modified":
+                        added = info.get("added", 0)
+                        removed = info.get("removed", 0)
+                    elif t and t.startswith("added"):
+                        added = info.get("added", info.get("size", 0))
+                        removed = 0
+                    elif t and t.startswith("removed"):
+                        added = 0
+                        removed = info.get("removed", info.get("size", 0))
+                if field == "size_diff":
+                    return added - removed
+                if field == "size_added":
+                    return added
+                if field == "size_removed":
+                    return removed
+            # timestamp diffs
+            if field in ("ctime_diff", "mtime_diff"):
+                it1 = getattr(d, "_item1", None)
+                it2 = getattr(d, "_item2", None)
+                base = field.split("_")[0]
+                t2 = it2.get(base, 0) if it2 is not None else 0
+                t1 = it1.get(base, 0) if it1 is not None else 0
+                return t2 - t1
+            # size of item in archive2
+            if field == "size":
+                it2 = getattr(d, "_item2", None)
+                if it2 is None or it2.get("deleted"):
+                    return 0
+                return it2.get_size()
+            # direct attributes from current item (prefer item2)
+            it = getattr(d, "_item2", None) or getattr(d, "_item1", None)
+            attr_defaults = {"user": "", "group": "", "uid": -1, "gid": -1, "ctime": 0, "mtime": 0}
+            if field in attr_defaults:
+                if it is None:
+                    return attr_defaults[field]
+                return it.get(field, attr_defaults[field])
+            raise ValueError(f"Invalid field name: {field}")
+
+        if sort_specs:
+            diffs = list(diffs)
+            # Apply stable sorts from last to first
+            for spec in reversed(sort_specs):
+                desc = False
+                field = spec
+                if field and field[0] in ("<", ">"):
+                    desc = field[0] == ">"
+                diffs.sort(key=lambda di: key_for(field, di), reverse=desc)
 
         formatter = DiffFormatter(format, args.content_only)
         for diff in diffs:
@@ -149,7 +227,87 @@ def build_parser_diff(self, subparsers, common_parser, mid_common_parser):
         """
             )
             + DiffFormatter.keys_help()
+            + textwrap.dedent(
+                """
+
+        What is compared
+        +++++++++++++++++
+        For each matching item in both archives, Borg reports:
+
+        - Content changes: total added/removed bytes within files. If chunker parameters are comparable,
+          Borg compares chunk IDs quickly; otherwise, it compares the content.
+        - Metadata changes: user, group, mode, and other metadata shown inline like
+          "[old_mode -> new_mode]" for mode changes. Use ``--content-only`` to suppress metadata changes.
+        - Added/removed items: printed as "added SIZE path" or "removed SIZE path".
+
+        Output formats
+        ++++++++++++++
+        The default (text) output shows one line per changed path, e.g.::
+
+            +135 B    -252 B [ -rw-r--r-- -> -rwxr-xr-x ] path/to/file
+
+        JSON Lines output (``--json-lines``) prints one JSON object per changed path, e.g.::
+
+            {"path": "PATH", "changes": [
+                {"type": "modified", "added": BYTES, "removed": BYTES},
+                {"type": "mode", "old_mode": "-rw-r--r--", "new_mode": "-rwxr-xr-x"},
+                {"type": "added", "size": SIZE},
+                {"type": "removed", "size": SIZE}
+            ]}
+
+        Sorting
+        ++++++++
+        Use ``--sort-by FIELDS`` where FIELDS is a comma-separated list of fields.
+        Sorts are applied stably from last to first in the given list. Prepend ">" for
+        descending, "<" (or no prefix) for ascending, for example ``--sort-by=">size_added,path"``.
+        Supported fields include:
+
+        - path: the item path
+        - size_added: total bytes added for the item content
+        - size_removed: total bytes removed for the item content
+        - size_diff: size_added - size_removed (net content change)
+        - size: size of the item as stored in ARCHIVE2 (0 for removed items)
+        - user, group, uid, gid, ctime, mtime: taken from the item state in ARCHIVE2 when present
+        - ctime_diff, mtime_diff: timestamp difference (archive2 - archive1)
+
+        The ``--sort`` option is deprecated and only sorts by path.
+
+        Performance considerations
+        ++++++++++++++++++++++++++
+        For archives created with Borg 1.1 or newer, diff automatically detects whether
+        the archives were created with the same chunker parameters. If so, only chunk IDs
+        are compared, which is very fast.
+        """
+            )
         )
+
+        def diff_sort_spec_validator(s):
+            if not isinstance(s, str):
+                raise argparse.ArgumentTypeError("unsupported sort field (not a string)")
+            allowed = {
+                "path",
+                "size_added",
+                "size_removed",
+                "size_diff",
+                "size",
+                "user",
+                "group",
+                "uid",
+                "gid",
+                "ctime",
+                "mtime",
+                "ctime_diff",
+                "mtime_diff",
+            }
+            parts = [p.strip() for p in s.split(",") if p.strip()]
+            if not parts:
+                raise argparse.ArgumentTypeError("unsupported sort field: empty spec")
+            for spec in parts:
+                field = spec[1:] if spec and spec[0] in (">", "<") else spec
+                if field not in allowed:
+                    raise argparse.ArgumentTypeError(f"unsupported sort field: {field}")
+            return ",".join(parts)
+
         subparser = subparsers.add_parser(
             "diff",
             parents=[common_parser],
@@ -172,7 +330,12 @@ def build_parser_diff(self, subparsers, common_parser, mid_common_parser):
             action="store_true",
             help="override the check of chunker parameters",
         )
-        subparser.add_argument("--sort", dest="sort", action="store_true", help="Sort the output lines by file path.")
+        subparser.add_argument(
+            "--sort",
+            dest="sort",
+            action="store_true",
+            help="Sort the output lines by file path (deprecated, use --sort-by=path).",
+        )
         subparser.add_argument(
             "--format",
             metavar="FORMAT",
@@ -181,6 +344,12 @@ def build_parser_diff(self, subparsers, common_parser, mid_common_parser):
             help='specify format for differences between archives (default: "{change} {path}{NL}")',
         )
         subparser.add_argument("--json-lines", action="store_true", help="Format output as JSON Lines.")
+        subparser.add_argument(
+            "--sort-by",
+            dest="sort_by",
+            type=diff_sort_spec_validator,
+            help="Sort output by comma-separated fields (e.g., '>size_added,path').",
+        )
         subparser.add_argument(
             "--content-only",
             action="store_true",

src/borg/testsuite/archiver/diff_cmd_test.py

@@ -404,3 +404,47 @@ def test_hard_link_deletion_and_replacement(archivers, request):
     assert_line_exists(lines, "added.*B.*input/a/hardlink")
     # But the b/hardlink file was not modified at all.
     assert_line_not_exists(lines, ".*input/b/hardlink")
+
+
+def test_sort_by_path_equivalence(archivers, request):
+    archiver = request.getfixturevalue(archivers)
+    cmd(archiver, "repo-create", RK_ENCRYPTION)
+
+    # Prepare first archive
+    create_regular_file(archiver.input_path, "a_file_removed", size=8)
+    create_regular_file(archiver.input_path, "f_file_removed", size=16)
+    create_regular_file(archiver.input_path, "c_file_changed", size=32)
+    create_regular_file(archiver.input_path, "e_file_changed", size=64)
+    cmd(archiver, "create", "test0", "input")
+
+    # Prepare second archive: simulate changes
+    os.unlink("input/a_file_removed")
+    os.unlink("input/f_file_removed")
+    os.unlink("input/c_file_changed")
+    os.unlink("input/e_file_changed")
+    create_regular_file(archiver.input_path, "c_file_changed", size=512)
+    create_regular_file(archiver.input_path, "e_file_changed", size=1024)
+    create_regular_file(archiver.input_path, "b_file_added", size=128)
+    create_regular_file(archiver.input_path, "d_file_added", size=256)
+    cmd(archiver, "create", "test1", "input")
+
+    # New sorter should behave like legacy --sort when using path
+    output = cmd(archiver, "diff", "test0", "test1", "--sort-by=path", "--content-only")
+    expected = ["a_file_removed", "b_file_added", "c_file_changed", "d_file_added", "e_file_changed", "f_file_removed"]
+    assert isinstance(output, str)
+    outputs = output.splitlines()
+    assert len(outputs) == len(expected)
+    assert all(x in line for x, line in zip(expected, outputs))
+
+
+def test_sort_by_invalid_field_is_rejected(archivers, request):
+    archiver = request.getfixturevalue(archivers)
+    cmd(archiver, "repo-create", RK_ENCRYPTION)
+
+    create_regular_file(archiver.input_path, "file", size=1)
+    cmd(archiver, "create", "a1", "input")
+    create_regular_file(archiver.input_path, "file", size=2)
+    cmd(archiver, "create", "a2", "input")
+
+    # Unsupported field should cause argument parsing error
+    cmd(archiver, "diff", "a1", "a2", "--sort-by=not_a_field", exit_code=EXIT_ERROR)