compare_snapshots#

qx_utilities.general.snapshots.compare_snapshots(before, after, outfile, includehash=True, exclude=None)#

compare_snapshots before=<path to snapshot file> after=<path to snapshot file or folder> outfile=<path to comparison file> [includehash=True] [exclude=None]

Compares two directory snapshots or a snapshot against a live directory to identify changes. Creates a detailed comparison tree showing which files were added, deleted, or modified. The comparison can be used for change analysis or as input to rollback_snapshot() for reverting changes.

Parameters

--before (str):

Path to the "before" snapshot file (baseline state). This must be a snapshot file created by record_snapshot(). The snapshot captures the original state before changes were made.

--after (str):

Path to either:

  • A snapshot file created by record_snapshot() (for comparing two snapshots from different times)

  • A directory path (the function will create a temporary snapshot of the current state for comparison)

This represents the state after changes were made.

--outfile (str):

Path to the output file where the comparison results will be saved. The file will contain a tree structure with status markers showing all changes. If the file exists, it will be overwritten.

--includehash (bool or str, default True):

Whether to use MD5 hash when detecting modifications:

  • True: Files are considered modified if modification time, size, OR hash differs. Most accurate but only works if both snapshots included hashes.

  • False: Files are considered modified only if modification time or size differs. Faster and works even if snapshots lack hashes.

Can be specified as boolean or string ("true", "false", "yes", "no").

--exclude (list or str, default None):

Optional list of files or folders to exclude from the comparison. Excluded items will not appear in the comparison output. Can be specified as:

  • List of paths: ['temp', 'cache', 'logs/debug.log']

  • Comma-separated string: 'temp, cache, logs/debug.log'

  • Quoted strings for spaces: "'build output', cache"

If 'after' is a directory (not a snapshot file), the exclude list is passed to record_snapshot when creating the temporary snapshot.

Comparison Output Format:

The output file uses a tree structure with status markers:

before: /home/user/project/data
after: /home/user/project/data
.
  ├── configs
  │   ├── settings.json              [2024-01-15 10:23:45.123456, a1b2c3d4, 1024 bytes]
  │   └── database.ini               [2024-01-15 10:23:45.234567, e5f6g7h8, 512 bytes]
+ ├── new_data
+ │   └── results.csv                [2024-01-15 12:00:00.123456, x1y2z3a4, 8192 bytes]
M ├── data
M │   └── input.txt                  [2024-01-15 10:25:30.345678 -> 2024-01-15 14:30:00.123456, ...]
- └── old_file.txt                   [2024-01-14 09:00:00.000000, q7r8s9t0, 256 bytes]
Status Markers:

  • + (Added): File or folder exists in 'after' but not in 'before'

  • - (Deleted): File or folder exists in 'before' but not in 'after'

  • M (Modified): File metadata changed between snapshots (time, size, or hash)

  • ** ** (Unchanged): File or folder unchanged (two spaces, no marker)

Modification Detection:

Files are considered modified when:

  1. Modification time differs (always checked)

  2. File size differs (always checked)

  3. MD5 hash differs (only if includehash=True AND both snapshots have hashes)

For modified files, metadata shows before → after values.

Use Cases:

  • Change auditing: See exactly what changed in a directory tree

  • Quality control: Verify that processing modified only expected files

  • Rollback preparation: Identify files to remove when reverting changes

  • Documentation: Create a record of changes for compliance or debugging

Notes

  • If 'after' is a directory, a temporary snapshot is created automatically

  • Hash comparison only works if both snapshots included hashes

  • The comparison file can be used directly with rollback_snapshot()

  • Comparison is smart: directories marked modified only if children changed

  • Empty directories are tracked (shown as added/deleted if they change)

Examples

Compare two snapshot files:

compare_snapshots(
    before="/snapshots/before_processing.txt",
    after="/snapshots/after_processing.txt",
    outfile="/snapshots/diff_processing.txt",
)

Compare snapshot against current directory state:

compare_snapshots(
    before="/snapshots/baseline.txt",
    after="/path/to/project/data",
    outfile="/snapshots/current_changes.txt",
)

Fast comparison without hash checking:

compare_snapshots(
    before="/snapshots/baseline.txt",
    after="/path/to/project/data",
    outfile="/snapshots/quick_diff.txt",
    includehash=False,
)