dirval 1.1.3

Create and validate a directory stamp based on deterministic path hashing.

Directory Validator (dirval) 📂✅

Directory Validator is a Python utility that creates and verifies a unique hash stamp for a directory. This stamp, saved as a JSON file, represents the directory’s structure (relative paths, excluding the stamp file itself), allowing you to quickly detect changes in the directory layout.

🛠 Features

• Stamp Creation: Generate a deterministic SHA-256 hash from all relative paths (files and subdirectories).
• Validation: Recalculate the hash to determine if any files or directories have changed.
• Exclusion Handling: Automatically ignores the stamp file (directory_stemp.json) in the directory root.
• Simple CLI Interface: Easily create or validate stamps via command-line options.

📥 Installation

Install Directory Validator directly from PyPI:

pip install dirval

For a user-local installation (recommended if you don’t use virtual environments):

pip install --user dirval

For development or editable installs:

git clone https://github.com/kevinveenbirkenbach/directory-validator.git
cd directory-validator
pip install -e .

After installation, the dirval command will be available in your shell.

🚀 Usage

Create a Directory Stamp

Generate a stamp (hash and timestamp) for a directory. The stamp is saved as directory_stemp.json inside the directory.

dirval <path_to_directory> --stamp

Example:

dirval ./my-folder --stamp

Validate a Directory

Compare the current directory state against the stored stamp to check for any modifications.

dirval <path_to_directory> --validate

Example:

dirval ./my-folder --validate

Exit codes:

• 0 → directory matches the stored stamp
• 1 → directory has changed
• 3 → directory or stamp file not found

📖 How It Works

• The tool recursively walks through the given directory and collects all file and subdirectory paths.
• The stamp file (directory_stemp.json) in the directory root is ignored automatically.
• All collected relative paths are sorted deterministically.
• A cumulative SHA-256 hash is generated from those paths.
• The hash and a timestamp are stored in directory_stemp.json.
• During validation, the hash is recalculated and compared against the stored value.

🧑‍💻 Author

Developed by Kevin Veen-Birkenbach

• 🌐 veen.world

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

🤝 Contributions

Contributions are welcome! Feel free to fork the repository, submit pull requests, or open issues if you have suggestions or encounter any problems. Let's improve directory validation together! 😊