From 541b01d48a5adba903fb6043df0dcc23e82afad0 Mon Sep 17 00:00:00 2001 From: "Bryn M. Reeves" Date: Tue, 12 May 2026 19:22:22 +0100 Subject: [PATCH] Warn users that diff operations compare whole file system by default Resolves: RHEL-174474 Signed-off-by: Bryn M. Reeves --- ...-when-no-s-start-path-Options.from_p.patch | 42 ++++++++++++ ...ult-diff-start-path-behaviour-in-sna.patch | 48 ++++++++++++++ ...on-of-s-start-path-to-user_guide.rst.patch | 66 +++++++++++++++++++ snapm.spec | 5 +- 4 files changed, 160 insertions(+), 1 deletion(-) create mode 100644 0002-fsdiff-warn-user-when-no-s-start-path-Options.from_p.patch create mode 100644 0003-doc-clarify-default-diff-start-path-behaviour-in-sna.patch create mode 100644 0004-doc-add-discussion-of-s-start-path-to-user_guide.rst.patch diff --git a/0002-fsdiff-warn-user-when-no-s-start-path-Options.from_p.patch b/0002-fsdiff-warn-user-when-no-s-start-path-Options.from_p.patch new file mode 100644 index 0000000..6b65ca8 --- /dev/null +++ b/0002-fsdiff-warn-user-when-no-s-start-path-Options.from_p.patch @@ -0,0 +1,42 @@ +From a8ded86017e1bdce8e2b5f3e69b1d798312d63f4 Mon Sep 17 00:00:00 2001 +From: "Bryn M. Reeves" +Date: Mon, 30 Mar 2026 13:44:57 +0100 +Subject: [PATCH 02/10] fsdiff: warn user when no + -s/--start-path/Options.from_path given + +Unless -q/--quiet/Options.quiet is specified issue a warning to the +termional when a diff operation does not have any explicit start path +defined (since these can almost always reasonably be assumed to be slow +and costly). + + # snapm snapset diff before-upgrade . + WARNING - Consider setting -s/--start-path to reduce diff runtime and memory usage + Gathering paths from before-upgrade /: Quit! + +Resolves: #968 + +Suggested-by: Filip Suba +Signed-off-by: Bryn M. Reeves +--- + snapm/fsdiff/fsdiffer.py | 5 +++++ + 1 file changed, 5 insertions(+) + +diff --git a/snapm/fsdiff/fsdiffer.py b/snapm/fsdiff/fsdiffer.py +index bd64f076..f9e2cf4f 100644 +--- a/snapm/fsdiff/fsdiffer.py ++++ b/snapm/fsdiff/fsdiffer.py +@@ -163,6 +163,11 @@ class FsDiffer: + if options.no_mem_check: + _log_warn("RSS memory pressure safety checks disabled") + ++ if not options.from_path and not options.quiet: ++ _log_warn( ++ "Consider setting -s/--start-path to reduce run time and memory usage" ++ ) ++ + #: Manager context for snapshot operations (used by future methods) + self.manager: "Manager" = manager + self.options: DiffOptions = options +-- +2.53.0 + diff --git a/0003-doc-clarify-default-diff-start-path-behaviour-in-sna.patch b/0003-doc-clarify-default-diff-start-path-behaviour-in-sna.patch new file mode 100644 index 0000000..7625b80 --- /dev/null +++ b/0003-doc-clarify-default-diff-start-path-behaviour-in-sna.patch @@ -0,0 +1,48 @@ +From 8d74490b35cb9592f554c4b5804fe0d4e5b6c77c Mon Sep 17 00:00:00 2001 +From: "Bryn M. Reeves" +Date: Tue, 31 Mar 2026 13:04:52 +0100 +Subject: [PATCH 03/10] doc: clarify default diff start path behaviour in + snapm.8 + +Related: #959 + +Signed-off-by: Bryn M. Reeves +--- + man/man8/snapm.8 | 14 ++++++++++++++ + 1 file changed, 14 insertions(+) + +diff --git a/man/man8/snapm.8 b/man/man8/snapm.8 +index 9baad38e..dcc20ee9 100644 +--- a/man/man8/snapm.8 ++++ b/man/man8/snapm.8 +@@ -1081,6 +1081,13 @@ Calculates the differences between the \fBfrom\fP and \fBto\fP targets. Targets + may be specified as a snapshot set name, or the special character \fB.\fP to + represent the currently running system (root file system). + .IP ++If \fB--start-path\fP is not specified the comparison proceeds from the root ++directory of the two volumes. This can be costly in terms of both time and ++memory: for better performance, specify one or more start paths in order to ++focus the difference generation on areas of interest. A resource use warning is ++emitted if no start path is given (this warning can be suppressed using the ++\fB--quiet\fP argument). ++.IP + The output format is controlled by \fB--output-format\fP. The \fBtree\fP + format provides a hierarchical view of changes, while \fBdiff\fP provides + standard unified diff output for modified content: see \fBOutput Formats\fP for +@@ -1155,6 +1162,13 @@ Compare snapshot sets and output results in a tabular report. + Performs the same comparison logic as \fBsnapm snapset diff\fP but formats + the output as a report using the standard reporting columns. + .IP ++If \fB--start-path\fP is not specified the comparison proceeds from the root ++directory of the two volumes. This can be costly in terms of both time and ++memory: for better performance, specify one or more start paths in order to ++focus the difference generation on areas of interest. A resource use warning is ++emitted if no start path is given (this warning can be suppressed using the ++\fB--quiet\fP argument). ++.IP + This command supports standard reporting arguments including \fB--options\fP, + \fB--sort\fP, \fB--noheadings\fP, and \fB--json\fP. + .TP +-- +2.53.0 + diff --git a/0004-doc-add-discussion-of-s-start-path-to-user_guide.rst.patch b/0004-doc-add-discussion-of-s-start-path-to-user_guide.rst.patch new file mode 100644 index 0000000..0b712a7 --- /dev/null +++ b/0004-doc-add-discussion-of-s-start-path-to-user_guide.rst.patch @@ -0,0 +1,66 @@ +From 88d4a0e5f4d7d619d58ecdc47a8a4f0ae74a21eb Mon Sep 17 00:00:00 2001 +From: "Bryn M. Reeves" +Date: Tue, 31 Mar 2026 16:23:30 +0100 +Subject: [PATCH 04/10] doc: add discussion of -s/--start-path to + user_guide.rst + +Resolves: #959 + +Signed-off-by: Bryn M. Reeves +--- + doc/user_guide.rst | 19 +++++++++++++++++++ + 1 file changed, 19 insertions(+) + +diff --git a/doc/user_guide.rst b/doc/user_guide.rst +index 6acfb943..71fee02b 100644 +--- a/doc/user_guide.rst ++++ b/doc/user_guide.rst +@@ -219,6 +219,11 @@ changes: + ownership (UID/GID), and extended attributes (xattrs). + * **Content Comparison**: Performs deep content comparisons for regular + files, including generating standard unified diffs for text files. ++* **Start Path Control**: By default difference engine operations proceed from ++ the root directory of snapshot sets (or the system root file system). This ++ can be overridden by specifying one or more start paths for the comparison. ++ This allows the user to focus the operation on areas of interest and lowers ++ run time and memory consumption. + + Output Formats and Use Cases + ---------------------------- +@@ -294,6 +299,14 @@ resource-intensive. To improve performance, ``snapm`` implements a + ``--cache-expires=EXPIRES_SECS`` options. These options are mutually + exclusive. + ++By default a ``diff`` or ``diffreport`` command will start at the root mount ++of the respective snapshot set (or the system root file system). This can be ++costly both in terms of time and memory consumption. The comparison can be ++narrowed to specific directories of interest by specifying one or more start ++paths using ``-s|--start-path PATH``. If no start path is given the tools ++will warn about the potential resource use. This warning can be suppressed if ++desired using ``--quiet``. ++ + Command Reference + ================= + +@@ -479,12 +492,18 @@ ignoring file modification times to focus only on content: + + Options are available to control the comparison: + ++* ``--start-path PATH`` / ``-s PATH``: Begin comparison at ``PATH`` ++ (may be specified zero or more times) + * ``--content-only`` / ``-c``: Only check for file content changes + * ``--ignore-timestamps`` / ``-t``: Ignore modification times + * ``--ignore-permissions`` / ``-p``: Ignore permission changes + * ``--ignore-ownership`` / ``-w``: Ignore ownership changes + * ``--include-pattern`` / ``--exclude-pattern``: Filter paths using glob patterns + ++The ``PATH`` value given to ``--start-path PATH`` / ``-s PATH`` is evaluated ++relative to the root directory of the snapshot set (or system root file system ++when using ``.``). ++ + Output Formats + ~~~~~~~~~~~~~~ + +-- +2.53.0 + diff --git a/snapm.spec b/snapm.spec index 8dd195f..293909b 100644 --- a/snapm.spec +++ b/snapm.spec @@ -8,7 +8,10 @@ Summary: %{summary} License: Apache-2.0 URL: https://github.com/snapshotmanager/%{name} Source0: %{url}/archive/v%{version}/%{name}-%{version}.tar.gz -Patch1: 0001-tests-skip-a-handful-of-tests-in-RH-CI-environments-.patch +Patch0: 0001-tests-skip-a-handful-of-tests-in-RH-CI-environments-.patch +Patch1: 0002-fsdiff-warn-user-when-no-s-start-path-Options.from_p.patch +Patch2: 0003-doc-clarify-default-diff-start-path-behaviour-in-sna.patch +Patch3: 0004-doc-add-discussion-of-s-start-path-to-user_guide.rst.patch BuildArch: noarch