Dazzlesum

Dazzlesum is a handy checksum tool designed for data integrity verification across different machines and operating systems. It generates folder-specific checksum files (.shasum) that enable verification of file collections, with special attention to DOS shell compatibility and cross-platform consistency.

Features

• Multiple Hash Algorithms: SHA256 (default), SHA512, SHA1, MD5 with consistent cross-platform behavior
• Cross-Platform Support: Seamlessly handle checksums between Windows, macOS, Linux, and BSD
• DOS Compatibility: ASCII-only output that works perfectly in Windows Command Prompt
• In-Process Hashing Engine: Python hashlib (OpenSSL-backed) as the primary engine -- no per-file subprocess overhead; native system tools (certutil, shasum, fsum) remain as fallback for algorithms hashlib lacks
• Flexible Generation Modes: Individual .shasum files per directory, monolithic files, or both simultaneously
• Advanced Verification: Problems-only output shows only failed, missing, or extra files by default
• Management Operations: Backup, remove, restore, and list .shasum files with comprehensive metadata
• Enhanced Logging: 11-level verbosity system (-6 to +4) with granular output control and smart filtering
• Advanced Exit Codes: 7 different exit codes based on aggregate verification results for precise automation
• Squelch System: Filter specific message types (SUCCESS, NO_SHASUM) for customized output
• Context-Aware Operations: Auto-detects whether to create or verify based on directory contents
• Shadow Directory Support: Keep source directories clean by storing checksum files in parallel shadow structure

Use Cases

🔧 Data Integrity Verification

Maintain consistent checksum verification across different operating systems. Generate checksums on your Windows machine and verify them on your Linux environment without losing any data integrity checks.

⚙️ System Administration

Simplify management of complex directory structures and checksum file collections. Document and reproduce checksum configurations for backup or disaster recovery scenarios.

📁 Content Organization

Create organizational structures using checksum verification, then export and share these verification systems with others. Perfect for media libraries (similar to SFVs), project references, or any scenario where data integrity needs to be maintained across multiple locations.

🌐 Network Path Management

Automatically handle different representations of network paths across systems while maintaining all checksum metadata and verification capabilities.

Installation

Prerequisites

• Python 3.9 or higher
• Operating System: Windows, macOS, Linux, BSD
• Dependencies: dazzle-lib and dazzle-filekit, installed automatically by pip. UNC-aware path handling comes through filekit, which is backed by unctools
• The standalone dazzlesum.py has no dependencies at all -- see Standalone below

Install from PyPI

pip install dazzlesum

Manual Installation

git clone https://github.com/DazzleTools/dazzlesum.git
cd dazzlesum
pip install -e .

On Windows:

pip install -e ".[windows]"

Other potential dependencies down the line:

pip install -e ".[dev,test,docs]"

Standalone (no install)

dazzlesum.py is a single self-contained file with no dependencies beyond the Python standard library. Copy it anywhere and run it directly:

python dazzlesum.py --help

Quick Start

Generate checksums (using new subcommand syntax)

Every command takes an optional directory argument. Leave it off to work on the current directory, or name any folder -- local, relative, or a network share:

# Generate checksums for current directory
dazzlesum create

# Generate checksums recursively
dazzlesum create -r

# ...or point it anywhere else
dazzlesum create -r \\server\share\backups

# Create monolithic checksum file
dazzlesum create -r --mode monolithic

# Generate with verbose output (11 levels available: -6 to +4)
dazzlesum create -r -vv

# Silent mode for automation
dazzlesum verify -r -qqqqqq

# Problems-only with custom squelch filters
dazzlesum verify -r --squelch=SUCCESS,NO_SHASUM

# Keep source directories clean with shadow directory
dazzlesum create -r --shadow-dir ./checksums

# Generate monolithic checksum in shadow directory
dazzlesum create -r --mode monolithic --shadow-dir ./checksums

Verify checksums

# Verify existing checksums
dazzlesum verify -r

# Verify with detailed output
dazzlesum verify -r -v

# Show all verification results
dazzlesum verify -r --show-all-verifications

# Verify checksums stored in shadow directory
dazzlesum verify -r --shadow-dir ./checksums

Update checksums

# Update existing checksums for changed files
dazzlesum update -r

# Update only specific file types
dazzlesum update -r --include "*.txt,*.doc"

Manage checksum files

# Backup all .shasum files
dazzlesum manage -r backup --backup-dir ./checksum-backup

# List all .shasum files with details
dazzlesum manage -r list

# Remove all .shasum files (with confirmation)
dazzlesum manage -r remove

# Restore from backup
dazzlesum manage -r restore --backup-dir ./checksum-backup

Get help

# General help
dazzlesum --help

# Help for specific commands
dazzlesum create --help
dazzlesum verify --help

# Detailed help topics
dazzlesum mode        # Help for --mode parameter
dazzlesum examples    # Comprehensive usage examples
dazzlesum shadow      # Shadow directory help

Documentation

• Installation Guide - Detailed installation instructions for all platforms
• Usage Examples - Practical examples for common use cases
• Shadow Directory Guide - Complete guide to shadow directory operations
• Command Reference - Complete command-line reference
• File Formats - Details about .shasum file formats and compatibility

Platform Support

Windows, Linux, macOS, and BSD. Hashing runs in-process via Python hashlib on every platform; native tools are a fallback for algorithms it lacks. Text files are line-ending normalized before hashing, so manifests generated on one platform verify on another. Junctions and symlinks are not followed by default.

See docs/platforms.md for the verification matrix, per-platform behavior, and the reasoning behind the hashing engine order.

Requirements

• Python: 3.9 or higher
• Operating System: Windows, macOS, Linux, BSD -- see docs/platforms.md
• Dependencies: dazzle-lib and dazzle-filekit for the pip package (installed automatically); none at all for the standalone dazzlesum.py

Future Possible Features

• Compression: Archive support for checksum collections
• Remote Storage: Cloud backup integration? (maybe)

Contributing

Contributions are welcome! Issues, suggestions, and bug reports are all appreciated. Please open an issue if you find something that can be improved. Or:

1. Fork this repository and clone a fork.
2. Make changes on a new branch (e.g., feature/new_thing).
3. Submit a pull request describing your changes.

Please see CONTRIBUTING.md for detailed guidelines.

Like the project?

License

dazzlesum, Copyright (C) 2026 Dustin Darcy

Licensed under the GNU General Public License v3.0 (GPL-3.0) -- see LICENSE

Changelog

See CHANGELOG.md for version history and release notes.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Check the docs/ folder for additional guides

Made with ️☕. Designed for reliable, consistent data integrity verification across all platforms.