record_snapshot#

qx_utilities.general.snapshots.record_snapshot(targetfolder, outfile, includehash=True, exclude=None)#

record_snapshot targetfolder=<path to folder> outfile=<path to snapshot file> [includehash=True] [exclude=None]

Creates a hierarchical snapshot of a directory structure, recording file names, modification times, sizes, and optionally MD5 hashes. The snapshot is saved as a human-readable tree structure in a text file, which can later be used for comparison or rollback operations.

Parameters

--targetfolder (str):

The path to the folder to snapshot. The function recursively traverses all subdirectories and captures metadata for every file. The folder must exist or an error will be raised.

--outfile (str):

The path to the output text file where the snapshot will be saved. If the file exists, it will be overwritten. Parent directories will be created automatically if they don't exist.

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

Whether to compute and include MD5 hash for each file:

  • True: Compute MD5 hash for all files (slower but more accurate for detecting modifications)

  • False: Skip hash computation (faster, relies only on modification time and file size for change detection)

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 snapshot. Excluded items will not appear in the snapshot output. Can be specified as:

  • List of paths: ['temp', 'cache', 'logs/debug.log'] - excludes these specific files or folders (relative to targetfolder)

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

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

Exclusions are matched against relative paths from the target folder root. If a folder is excluded, all its contents are also excluded.

Snapshot Format:

The snapshot file uses a tree structure with Unicode box-drawing characters:

  • Directories are shown with branch lines (├──, └──, │)

  • Files include metadata aligned to column 80

  • Metadata format: [mtime, hash, size bytes] or [mtime, size bytes]

  • Modification time includes microseconds for precision

Example output:

/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]
├── data
│   ├── input.txt                  [2024-01-15 10:25:30.345678, i9j0k1l2, 2048 bytes]
│   └── processed
│       └── output.csv             [2024-01-15 11:00:00.456789, m3n4o5p6, 4096 bytes]
└── README.md                      [2024-01-15 09:00:00.567890, q7r8s9t0, 256 bytes]
Metadata Components:

  • Modification time: File's last modification timestamp with microsecond precision (format: YYYY-MM-DD HH:MM:SS.ffffff)

  • MD5 hash: 32-character hexadecimal hash of file contents (if includehash=True)

  • File size: Size in bytes

Use Cases:

  • Baseline creation: Capture the state of a directory before making changes

  • Change tracking: Monitor what files were added, modified, or deleted

  • Documentation: Record the exact state of data or configuration files

  • Rollback preparation: Create snapshots before risky operations

Notes

  • Hash computation can be slow for large files or many files

  • Snapshots capture file metadata, not file contents

  • Modification times are preserved with microsecond precision

  • The snapshot is a text file, not a backup of the actual files

  • Can be compared with other snapshots using compare_snapshots()

  • Can be used for rollback operations with rollback_snapshot()

Examples

Create snapshot with hashes:

record_snapshot(
    targetfolder="/path/to/project/data",
    outfile="/path/to/snapshots/baseline.txt",
)

Create fast snapshot without hashes:

record_snapshot(
    targetfolder="/path/to/project/data",
    outfile="/path/to/snapshots/quick_check.txt",
    includehash=False,
)