rollback_snapshot#

qx_utilities.general.snapshots.rollback_snapshot(diff=None, before=None, after=None, includehash=True, action='check', exclude=None, _log=None)#

rollback_snapshot [diff=<path to comparison file>] [before=<path to snapshot file>] [after=<path to snapshot file or folder>] [includehash=True] [action="check"] [exclude=None]

Analyzes snapshot differences to identify added files and optionally deletes them to roll back changes. Useful for reverting unwanted modifications, cleaning up failed processing runs, or undoing experimental changes. Can operate in two modes: check (analyze only) or delete (perform rollback).

Parameters

--diff (str, optional):

Path to a comparison file created by compare_snapshots(). If provided, this file is used directly to determine what changed. If not provided, both 'before' and 'after' parameters must be specified to generate the comparison on-the-fly.

--before (str, optional):

Path to the "before" snapshot file (baseline state). Required if 'diff' is not provided. This snapshot represents the state you want to roll back to.

--after (str, optional):

Path to either a snapshot file or a directory representing the current state. Required if 'diff' is not provided. If a directory is provided, a temporary snapshot will be created for comparison.

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

Whether to use MD5 hash when comparing files (only relevant if generating comparison on-the-fly). If using an existing diff file, this parameter is ignored.

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

--action (str, default "check"):

The action to perform:

  • "check": Analyze changes and show what would be deleted, but don't actually delete anything. Safe for previewing rollback operations.

  • "delete": Actually delete added files to perform the rollback. Use with caution - deleted files cannot be recovered unless you have backups.

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

Optional list of files or folders to exclude from rollback operations. Excluded files will not be deleted even if they were added. 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 generating a comparison on-the-fly (using before/after parameters), the exclude list is passed to compare_snapshots.

Rollback Behavior:

The function categorizes all changes into three types:

  1. Added files (+ marker): - Can be automatically rolled back by deletion - In "delete" mode, these files are removed from disk - In "check" mode, lists files that would be deleted

  2. Modified files (M marker): - Cannot be automatically rolled back - Original content is not stored in snapshots - Warning is displayed listing these files - Manual intervention required to restore original state

  3. Deleted files (- marker): - Cannot be automatically restored - Original file content is not stored in snapshots - Warning is displayed listing these files - Manual intervention required to restore from backups

Output Information:

The function provides detailed information about:

  • Total number of changes detected (added/modified/deleted)

  • List of files that can be automatically rolled back

  • List of files that require manual intervention

  • In "delete" mode: confirmation of files successfully deleted

  • In "delete" mode: errors if any deletions fail

Safety Features:

  • Default action is "check" (non-destructive preview)

  • Clear warnings about files that cannot be auto-rolled back

  • Detailed output before performing any deletions

  • Reports both successful and failed deletion attempts

Use Cases:

  • Undo failed processing: Remove files created by a failed analysis run

  • Clean up experiments: Revert changes from experimental code

  • Quality control: Preview what would be rolled back before committing

  • Partial rollback: Understand what can/cannot be automatically reverted

Limitations:

  • Only added files can be automatically removed

  • Modified files cannot be restored (original content not in snapshot)

  • Deleted files cannot be recovered (content not in snapshot)

  • Snapshots record metadata only, not file contents

  • For full rollback capability, use backup_files() before making changes

Notes

  • Always run with action="check" first to preview changes

  • The function extracts the target directory path from the diff file

  • Empty directories are not removed (only files)

  • If any deletion fails, the function continues with remaining files

  • Consider using backup_files() for reversible operations

Examples

Preview rollback using existing diff:

rollback_snapshot(
    diff="/snapshots/processing_diff.txt",
    action="check",
)

Actually perform rollback:

rollback_snapshot(
    diff="/snapshots/processing_diff.txt",
    action="delete",
)

Rollback with on-the-fly comparison:

rollback_snapshot(
    before="/snapshots/baseline.txt",
    after="/path/to/project/data",
    action="check",
)

Quick preview without hash comparison:

rollback_snapshot(
    before="/snapshots/baseline.txt",
    after="/path/to/project/data",
    includehash=False,
    action="check",
)