dirhash-python

dirhash is a Python module and command-line tool for computing a single, deterministic hash of an entire file system directory based on the Dirhash Standard. The hash reflects both the contents of every file and the structure of the directory tree, so two directories produce the same hash if and only if they are equivalent.

It supports flexible inclusion and exclusion of files via glob patterns, a choice of underlying hash algorithms, and multiprocessing for fast hashing of large directory trees, making it well suited to caching, integrity checks, and reproducibility.

What You Get

• A single deterministic hash for an entire directory’s contents and structure
• Both an importable Python API and a command-line interface
• Glob-based match and ignore filters to include or exclude specific files
• A choice of hash algorithms from Python’s hashlib
• Optional multiprocessing to speed up hashing of large trees

Common Use Cases

• Detecting whether the contents of a directory have changed
• Keying a build or computation cache on the exact state of an input folder
• Verifying the integrity of downloaded or synced directory trees
• Comparing two directories for content and structural equivalence

Under The Hood

Architecture - The core logic lives in src/dirhash/init.py, which walks the directory tree, applies match/ignore glob filters, hashes each file’s contents together with its relative path, and combines the per-file digests into a single directory hash defined by the Dirhash Standard. A thin cli.py wraps this API for shell use, and multiprocessing can distribute per-file hashing across workers.

Tech Stack - Pure Python packaged with setuptools via setup.py/setup.cfg and pyproject.toml, relying on the standard-library hashlib for algorithms and a small scantree dependency for efficient directory traversal.

Code Quality - The repository includes a tests/ directory with test_dirhash.py and test_cli.py, a CHANGELOG, and codecov configuration, indicating coverage of both the library and CLI, though recent development activity is low.

API Design - The public API is small and approachable: a single dirhash() call takes a directory and options like algorithm, match, and ignore, returning a hex digest. Defaults are sensible, and the CLI mirrors the library options directly, so there is minimal boilerplate to get a result.