directory hash

Data & Storage

Meaning

A directory hash is a cryptographic digest computed over the entire contents and structure of a directory. It yields a single identifier that changes whenever any file is added, removed, or modified, allowing quick detection of modifications. It is used whenever you need to verify the integrity of a whole directory or to cache results based on its state.

Primary Function

Integrity verification

Communicative Purpose

Ensures that a directory’s contents have not been altered.

Pattern

compute directory hash → compare with stored hash → detect changes

Core Structure

directory_hash = hash( sorted( (relative_path, file_hash) for each file in directory ) )

Função primária

Integrity verification

Propósito comunicativo

Ensures that a directory’s contents have not been altered.

Situações de gatilho

Build systems: detecting changes in source directories before triggering a rebuild; Backup utilities: verifying that a restored directory matches the original snapshot; Cache invalidation: determining when cached artifacts need refresh due to file changes

Contextos

Continuous integration pipelines, deployment scripts, backup tools, file synchronization utilities, content-addressable storage systems

Padrão

compute directory hash → compare with stored hash → detect changes

Estrutura central

directory_hash = hash( sorted( (relative_path, file_hash) for each file in directory ) )

Colocados típicos

checksum
fingerprint
Merkle tree
manifest
incremental hash

Substituições comuns

Using file modification timestamps instead of content hash – faster but can miss content changes
Using a single archive checksum (e.g.
zip hash) – simpler but cannot pinpoint which file changed

Erros comuns

Hashing only file names – misses content changes; Ignoring file permissions – leads to false negatives on systems where permissions matter; Not normalizing line endings – causes different hashes on Windows vs Unix; Including temporary files – inflates hash and triggers unnecessary rebuilds

Similar / contraste

File hash – hashes a single file, not the whole directory; Merkle tree directory hash – hierarchical hash that can isolate changed sub‑trees; Archive checksum – hashes a packaged archive rather than the live directory structure

Interferências

Coming from Git: assuming a directory hash is stable across operating systems – line‑ending differences cause mismatches → normalize line endings or use binary mode when reading files

Família do chunk

hashing
checksum
integrity verification
caching
content addressing

Nuance

Do not use for extremely large directories where hashing would be I/O‑bound; Computing the hash requires reading every file, so it incurs O(N) time and disk bandwidth; Symbolic links, file permissions, and timestamps can affect the resulting hash if not handled consistently

Efeito pragmático

Enables reliable cache invalidation and integrity checks, preventing deployment of stale or corrupted artifacts.

Dica de memória

A directory hash is like a building’s blueprint number – change any room and the number changes.

Nota

Prefer a cryptographic hash function such as SHA‑256 to minimise collision risk.

Upgrade path

Merkle tree directory hash

Frequência: HighFormulaicidade: FixedTipo de construção: conceptPrioridade de aquisição: Recognition firstPrioridade de output: BothTag de espaçamento: Short-term

Examples

import hashlib, os def directory_hash(path): sha = hashlib.sha256() for root, dirs, files in os.walk(path): for name in sorted(files): file_path = os.path.join(root, name) rel_path = os.path.relpath(file_path, path).replace(os.sep, '/') sha.update(rel_path.encode('utf-8')) with open(file_path, 'rb') as f: while chunk := f.read(8192): sha.update(chunk) return sha.hexdigest() print(directory_hash('my_project'))

import hashlib from pathlib import Path def dir_hash(root: Path) -> str: hasher = hashlib.sha256() for file_path in sorted(p for p in root.rglob('*') if p.is_file()): rel = file_path.relative_to(root).as_posix() hasher.update(rel.encode()) hasher.update(file_path.read_bytes()) return hasher.hexdigest() print(dir_hash(Path('/var/www')))

import hashlib, os def hash_directory(path, ignore=lambda p: p.startswith('.')): sha = hashlib.sha256() for root, _, files in os.walk(path): for name in sorted(files): if ignore(name): continue full = os.path.join(root, name) rel = os.path.relpath(full, path).replace(os.sep, '/') sha.update(rel.encode()) with open(full, 'rb') as f: for chunk in iter(lambda: f.read(65536), b''): sha.update(chunk) return sha.hexdigest() print(hash_directory('src', ignore=lambda n: n.endswith('.pyc')))