Fast, reproducible folder integrity verification using Merkle trees.

---

Overview

FolderHash is a PowerShell module for generating and verifying deterministic directory hashes using a Merkle tree.

Unlike traditional checksum tools that only calculate file hashes, FolderHash creates a hierarchical integrity index for an entire directory tree. By combining metadata hashes, content hashes, and Merkle tree node hashes, it can efficiently detect added, removed, or modified files while only recalculating hashes for items that have actually changed.

Each directory stores its own manifest as a .folderhash.json file, making the index portable, human-readable, and easy to inspect or version control.

FolderHash is designed to be:

• ⚡ Fast
• 🔒 Deterministic
• 📈 Incremental
• 📂 Portable
• 🔍 Transparent

Ideal for:

• Backup verification
• CI/CD pipelines
• Software release validation
• Digital archives
• File system monitoring
• Malware detection
• Long-term data preservation

---

Why FolderHash?

Traditional checksum tools are excellent for verifying individual files, but they become inefficient when working with entire directory trees. Every verification typically requires recalculating the hash of every file, regardless of whether anything has changed.

FolderHash takes a different approach. By organizing files into a deterministic Merkle tree and tracking metadata, it only recalculates hashes for files that have actually changed. This makes repeated integrity verification significantly faster while still providing strong cryptographic guarantees.

Traditional Checksums	FolderHash
Verify individual files	Verify entire directory trees
Rehash every file	Incremental rehashing
Flat file list	Hierarchical Merkle tree
No directory awareness	Directory-aware verification
Limited metadata support	Metadata-aware change detection
Optimized for files	Optimized for large directory structures

---

Features

• Deterministic directory hashing
• Merkle tree based directory verification
• Incremental hashing using metadata
• SHA-256, SHA-384 and SHA-512 support
• Human-readable JSON manifests
• Detects added, removed and modified files
• PowerShell native
• Efficient for large directory structures

---

Installation

Clone or download this repository and copy the FolderHash folder into one of your PowerShell module directories.

For example:

$env:USERPROFILE\Documents\PowerShell\Modules\

Then import the module:

Import-Module FolderHash

---

Quick Start

Create or update the directory hash index:

Set-FolderHash -Path "C:\Projects\Demo"

Verify directory integrity:

Compare-FolderHash -Path "C:\Projects\Demo"

Throw an exception if verification fails:

Assert-FolderHash -Path "C:\Projects\Demo"

Remove all FolderHash manifests:

Remove-FolderHashFiles -Path "C:\Projects\Demo"

---

Cmdlets

Set-FolderHash

Creates or updates the .folderhash.json manifest for a directory tree.

Set-FolderHash -Path "C:\Data" -Verbose

---

Compare-FolderHash

Verifies the integrity of a directory and returns a detailed result object.

FolderHash normally performs incremental verification. If a file's metadata matches the stored manifest, its content hash is not recalculated. If the metadata has changed, the file's content hash is recomputed to determine whether the file has actually been modified.

• -ForceDataCheck recalculates the content hash for every file, regardless of metadata.
• -NoDataCheck skips content hash verification. Any file whose metadata differs from the manifest is treated as changed.

Compare-FolderHash -Path "C:\Data"

Force verification of every file:

Compare-FolderHash -Path "C:\Data" -ForceDataCheck

Verify using metadata only:

Compare-FolderHash -Path "C:\Data" -NoDataCheck

Returns an object containing:

• IsValid
• ChangedFiles
• MissingFiles
• NewFiles
• ChangedDirectories

---

Assert-FolderHash

Verifies the integrity of a directory and throws an exception if verification fails.

FolderHash normally performs incremental verification. If a file's metadata matches the stored manifest, its content hash is not recalculated. If the metadata has changed, the file's content hash is recomputed to determine whether the file has actually been modified.

• -ForceDataCheck recalculates the content hash for every file, regardless of metadata.
• -NoDataCheck skips content hash verification. Any file whose metadata differs from the manifest is treated as changed.

Useful for automated validation, build pipelines, deployment verification, and security-sensitive scenarios.

Assert-FolderHash -Path "C:\Data"

Force verification of every file:

Assert-FolderHash -Path "C:\Data" -ForceDataCheck

Verify using metadata only:

Assert-FolderHash -Path "C:\Data" -NoDataCheck

---

Remove-FolderHashFiles

Removes all .folderhash.json files from a directory tree.

Remove-FolderHashFiles -Path "C:\Data" -Verbose

---

How It Works

FolderHash builds a deterministic Merkle tree representing the directory structure.

Each file contributes:

• Metadata hash
• Content hash
• Combined node hash

Each directory contributes:

• Metadata hash
• Combined hash of all child nodes
• Directory node hash

Only files whose metadata has changed need to be rehashed, making repeated integrity checks significantly faster.

Each directory contains a manifest named:

.folderhash.json

Example:

{
  "SchemaVersion": 1,
  "HashAlgorithm": "SHA512",
  "Items": [
    {
      "Key": "FILE:README.md",
      "Type": "File",
      "Name": "README.md",
      "MetadataHash": "...",
      "ContentHash": "...",
      "NodeHash": "..."
    }
  ]
}

Manifest entries contain:

• Key – Internal lookup key
• Type – File or Directory
• Name – Item name
• MetadataHash – Hash of file or directory metadata
• ContentHash – File contents or combined child hashes
• NodeHash – Final Merkle hash for the node

The root directory hash is represented by the root node's NodeHash.

---

Supported Hash Algorithms

FolderHash supports:

• SHA256
• SHA384
• SHA512

The selected algorithm is stored inside each manifest, allowing verification to use the same algorithm that was originally used when generating the index.

---

Project Structure

FolderHash/
│
├── assets/
│   ├── HeroBanner.png
│   ├── Logo.png
│   ├── Logo.svg
│   └── Logo.ico
│
├── Public/
│   ├── Set-FolderHash.ps1
│   ├── Compare-FolderHash.ps1
│   ├── Test-FolderHash.ps1
│   ├── Assert-FolderHash.ps1
│   └── Remove-FolderHashFiles.ps1
│
├── Private/
│   ├── Get-DirectoryHashNode.ps1
│   ├── Get-MetadataHash.ps1
│   ├── Get-StringHash.ps1
│   └── ...
│
├── FolderHash.psd1
├── FolderHash.psm1
├── LICENSE
└── README.md

---

Requirements

• PowerShell 7.0 or later
• Windows
• Linux
• macOS

---

License

This project is licensed under the MIT License.

See the LICENSE file for details.

---

Author

Robert Lindgren

<<<<<<< HEAD GitHub: https://github.com/RobertLindgrenSweden

GitHub: https://github.com/RobertLindgrenSweden

505ed14afcf806a5035ca9b151a7a311a1139886