Registry / devops / dirhash

dirhash

JSON →
library0.5.0pypypi✓ verified 29d ago

dirhash is a Python module and CLI tool for computing the hash of file system directories based on their structure and content. It supports all hashing algorithms available in Python's `hashlib` module, offers `.gitignore`-style glob/wildcard path matching for filtering files, and leverages multiprocessing for performance. The library computes hashes according to the Dirhash Standard, aiming for consistent and collision-resistant directory hash generation. It is actively maintained with irregular, feature-driven releases, currently at version 0.5.0.

pip install dirhash
INSTALL
IMPORT
SIG · DIRHASH
D
dirhash
devopspythonv0.5.0
Install
1.7s avg
Import
272ms
Disk
17MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.5.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.292s · 19.1MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.252s · 20MB
17MB installed
● package 17MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

dirhash
✓ from dirhash import dirhash

This quickstart demonstrates how to compute directory hashes using different algorithms and filtering options (`match` and `ignore` for `.gitignore` style patterns) using the `dirhash` function. It also shows the effect of including empty directories.

import os import tempfile import shutil from dirhash import dirhash # Create a temporary directory structure for demonstration with tempfile.TemporaryDirectory() as tmpdir: test_dir = os.path.join(tmpdir, 'my_project') os.makedirs(os.path.join(test_dir, 'src')) os.makedirs(os.path.join(test_dir, 'data')) with open(os.path.join(test_dir, 'src', 'main.py'), 'w') as f: f.write('print("Hello, dirhash!")') with open(os.path.join(test_dir, 'data', 'config.json'), 'w') as f: f.write('{"key": "value"}') with open(os.path.join(test_dir, '.gitignore'), 'w') as f: f.write('*.json') # Calculate the MD5 hash of the entire directory full_md5_hash = dirhash(test_dir, 'md5') print(f"MD5 hash of {test_dir}: {full_md5_hash}") # Calculate SHA1 hash, excluding .json files using .gitignore style patterns sha1_hash_no_json = dirhash(test_dir, 'sha1', ignore=['*.json']) print(f"SHA1 hash (excluding *.json): {sha1_hash_no_json}") # Calculate SHA256 hash, only including .py files sha256_hash_only_py = dirhash(test_dir, 'sha256', match=['*.py']) print(f"SHA256 hash (only *.py): {sha256_hash_only_py}") # Demonstrate including empty directories (default is to exclude if no content included by filters) # First, a hash without explicitly including empty dirs empty_dir_path = os.path.join(test_dir, 'empty_folder') os.makedirs(empty_dir_path) hash_without_empty = dirhash(test_dir, 'md5') print(f"MD5 hash (without explicit empty dirs): {hash_without_empty}") # Now, a hash explicitly including empty dirs hash_with_empty = dirhash(test_dir, 'md5', empty_dirs=True) print(f"MD5 hash (with empty dirs): {hash_with_empty}") # Cleanup is handled by TemporaryDirectory
dirhash --version
Debug
Known issues
breakingThe `pathspec` dependency's upper version limit was removed in `v0.4.0`. This change means that `dirhash` now uses `pathspec` versions greater than `0.10.0`. This update alters how some match/ignore patterns are treated, aligning behavior with `.gitignore` standards. Users upgrading from `v0.3.0` or earlier might observe different hash results for directories with complex filtering patterns.
fix
Review and test any existing directory hashing logic, especially those relying on `match` or `ignore` patterns, to ensure the new `.gitignore`-aligned behavior is as expected.
affects: >=0.4.0
breakingVersion `0.2.0` introduced 'significant breaking changes' from `v0.1.1`, primarily by adopting the formal 'Dirhash Standard'. This was a fundamental re-implementation that likely affected API calls and internal hash calculation logic.
fix
Users migrating from `v0.1.x` versions must thoroughly review the API and expected hash outputs against the new 'Dirhash Standard' implementation in `v0.2.0` and later.
affects: >=0.2.0
deprecatedPython 2.7 support was officially dropped in version `0.3.0`. The library now requires Python 3.8 or newer.
fix
Ensure your project is running on Python 3.8 or a newer compatible version.
affects: >=0.3.0
gotchaWindows support in `v0.5.0` is marked as 'experimental'. While `scantree>=0.0.4` was added for this purpose, users on Windows platforms may encounter platform-specific issues.
fix
Report any Windows-specific issues to the project's GitHub repository. Consider thorough testing on Windows environments before using in production.
affects: 0.5.0
gotchaThe default behavior regarding symbolic links, empty directories, and which file/directory properties (`name`, `data`, `is_link`) are included in the hash can significantly impact the resulting hash. Misunderstanding these options can lead to inconsistent or unexpected hash values. By default, `name` and `data` are included, but `is_link` is not.
fix
Carefully configure `empty_dirs`, `no_linked_dirs`, `no_linked_files`, `allow_cyclic_links`, and `properties` arguments to precisely define what should be included in the hash, especially in environments with complex file structures or symbolic links. Refer to the 'Dirhash Standard' documentation for detailed behavior.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'dirhash'
The 'dirhash' library is not installed in the Python environment.
fix
pip install dirhash
dirhash: error: the following arguments are required: directory
The command-line interface (CLI) for dirhash was called without specifying the target directory to hash.
fix
dirhash /path/to/directory
ValueError: Unsupported hashing algorithm: 'invalid_algo'
An invalid or unsupported hashing algorithm was provided to the `dirhash` function or CLI via the `-a` or `--algorithm` argument.
fix
Use a valid hashing algorithm from Python's hashlib, such as 'md5', 'sha1', 'sha256', 'sha512', etc.
Example: dirhash('/path/to/directory', 'sha256')
PermissionError: [Errno 13] Permission denied: '/path/to/inaccessible_file_or_dir'
The `dirhash` tool or function attempted to access a directory or file for which the current user lacks read permissions. This can also occur if a directory is not accessible and not explicitly excluded by filtering options.
fix
Ensure the user running `dirhash` has read permissions for all files and directories within the target path, or use the `ignore` argument (e.g., `--ignore 'path/to/inaccessible_dir/*'` in CLI or `ignore=['path/to/inaccessible_dir/*']` in Python) to exclude the inaccessible paths.
SyntaxError: invalid syntax (from shell when using unquoted glob patterns)
When using glob/wildcard patterns (like `*`) in the command line without quotes, the shell expands the pattern before `dirhash` receives it, leading to incorrect arguments or a syntax error if multiple files match.
fix
Always enclose glob/wildcard patterns in quotes when using them with `dirhash` on the command line.
Example: dirhash path/to/directory --match "*.py"
Upgrade
Version history
0.5.0latest on PyPI · released Aug 3, 2024
Audit
Dependencies
scantreerequiredRequired for experimental Windows support (introduced in v0.5.0).
pathspecrequiredUsed for .gitignore-style glob/wildcard path matching.
Agent activity
16 hits · last 30 days
node
12
OpenAI (training)
1
Resources
dirhash — pip install dirhash · libregistry