Hamidrezam — Safe, Intelligent Software-Project Backups

Hamidrezam (pip install hamidrezam) is a professional Python library + CLI that creates clean, optimized project archives while guaranteeing one non-negotiable invariant:

Hamidrezam NEVER modifies the source project.

Excluded files (node_modules, .venv, caches, build artifacts, …) are excluded only from the archive. They are never deleted, moved, renamed, or touched on disk. Hamidrezam streams selected files directly into the ZIP — no temporary cleaned copies.

pip install hamidrezam
hamidrezam backup ./my-project
# -> ./backups/my-project_2026-09-20_10-50-00.zip

Expected output:

✓ Project scanned
✓ Exclusions applied
✓ Archive created
✓ Manifest generated
✓ Archive verified

Why Hamidrezam?

Developer machines accumulate gigabytes of reproducible data: virtualenvs, node_modules, __pycache__, .next/, .tox/, ML runs, logs. Copying all of it for a backup is slow and wasteful — but hand-deleting it is dangerous. Hamidrezam automates the safe middle ground:

• Safe — read-only scan; source hashes unchanged (covered by a dedicated integrity test).
• Predictable — every decision has a reason (hamidrezam explain).
• Transparent — exclusion report + in-archive manifest with SHA-256 per file.
• Fast — single-pass streaming, chunked hashing, no temp copies.
• Cross-platform — pathlib throughout; Windows/Linux/macOS.
• Configurable — CLI > .hamidrezam.toml > global config > defaults.
• Scriptable & extensible — typed Python API + BackupWriter abstraction (ZIP today, tar.gz reserved).

Features

• Auto-detection of Python, Node.js/npm/pnpm/Yarn, React, Next.js, Vue, Nuxt, PHP, Laravel, Docker, AI/ML, generic/mixed projects.
• Sensible default exclusions (dependencies, venvs, caches, artifacts, temp, ML outputs) with opt-in knobs for dist//build/, IDE dirs, ML outputs.
• Secrets (.env*, secrets.json, …) and large-file policies: include / exclude / warn (default warn = include + warning).
• --dry-run planning, explain auditing, verify integrity checks, safe restore with traversal protection.
• Output-inside-source self-inclusion guard; never-silently-overwrite naming.
• Zero runtime dependencies (stdlib only; tomli backport on Python < 3.11).

Installation

pip install hamidrezam

Requires Python ≥ 3.9. Verify:

hamidrezam version
python -m hamidrezam version

Quick start

hamidrezam backup ./my-project
hamidrezam backup ./my-project --dry-run
hamidrezam backup ./my-project --include-git
hamidrezam backup ./my-project --format zip
hamidrezam backup . --exclude "*.log" --exclude "data/tmp/"
hamidrezam verify ./backups/my-project_2026-09-20_10-50-00.zip
hamidrezam restore ./backups/my-project_2026-09-20_10-50-00.zip ./restored --overwrite
hamidrezam explain ./my-project
hamidrezam list ./backups/my-project_2026-09-20_10-50-00.zip

CLI usage

hamidrezam backup <source> [--output ./backups] [--name NAME] [--format zip]
                     [--dry-run] [--include-git]
                     [--exclude GLOB]... [--include GLOB]...
                     [--secret-mode warn|include|exclude]
                     [--large-mode warn|include|exclude] [--max-size 2GB]
                     [--symlink-mode preserve|skip|follow] [--no-compression]
hamidrezam restore <backup.zip> <destination> [--overwrite]
hamidrezam verify <backup.zip> [--check-hashes]
hamidrezam explain <source>
hamidrezam list <backup.zip>
hamidrezam version
python -m hamidrezam <same as above>

Include/exclude precedence: output-safety > --include > protected source-of-truth files > --exclude > secrets/large policies > default rules > include. In short: explicit --include wins over default excludes; explicit --exclude still wins over protected files (your explicit choice); the archive can never include itself.

Python API

from hamidrezam import BackupManager, BackupConfig

manager = BackupManager()
result = manager.backup(source="./my-project", output="./backups")
print(result.archive_path, result.verified)

config = BackupConfig(include_git=False, secret_mode="warn", max_size="2GB")
manager = BackupManager(config=config)
dry = manager.backup("./project", dry_run=True)
print(dry.files_included, dry.files_excluded)

Typed results: BackupResult, ScanResult, VerificationResult, RestoreResult, BackupStatistics (with archive_path, files_included/excluded, bytes_included/excluded, duration, sha256, warnings, …).

Supported project types

No manual --type flag needed. Signals include pyproject.toml/requirements.txt/Pipfile → Python; package.json → Node.js (+ package-lock.json → npm, pnpm-lock.yaml → pnpm, yarn.lock → Yarn; react/next/vue/nuxt deps → frameworks); composer.json → PHP, artisan → Laravel; Dockerfile/docker-compose.yml/compose.yml → Docker; notebooks/wandb/.mlflow → AI/ML. Multiple labels can apply at once.

Default exclusions

Area	Excluded (from archive only)
Python	.venv/, venv/, env/, ENV/, __pycache__/, .pytest_cache/, .mypy_cache/, .ruff_cache/, .tox/, .nox/, .coverage, htmlcov/, *.pyc/pyo/pyd, *.egg-info/
Node/frontend	node_modules/, .npm/, .yarn/, .pnpm-store/, .next/, .nuxt/, .parcel-cache/, .turbo/, .cache/, coverage/
AI/ML	.ipynb_checkpoints/, .mlflow/, wandb/, runs/, logs/, .cache/ (+ outputs/, checkpoints/ unless include_outputs=true)
General	.cache/, tmp/, temp/, *.tmp, *.temp, .DS_Store, Thumbs.db, *.swp/swo
Build	dist/, build/ unless include_dist_build=true
IDE	.idea/, .vscode/ only when include=false (default true = preserved)
Git	.git/ unless --include-git / [git] include=true

Never excluded by default: README.md, LICENSE, .gitignore, .gitattributes, Dockerfile, compose files, package.json, lock files (package-lock.json, pnpm-lock.yaml, yarn.lock, poetry.lock, uv.lock, Pipfile.lock, composer.lock), requirements.txt, pyproject.toml, composer.json. Model weights (*.pt/.pth/.onnx/.safetensors/.ckpt/.bin) are never auto-excluded for being large — they trigger warn.

Configuration (.hamidrezam.toml)

Place in the project root; see examples/.hamidrezam.toml:

[backup]
format = "zip"
compression = true
output = "./backups"

[git]
include = false

[secrets]
mode = "warn"

[large_files]
mode = "warn"
max_size = "2GB"

[symlinks]
mode = "preserve"

[ide]
include = true

[build]
include_dist_build = false

[ml]
include_outputs = false

[custom]
exclude = ["*.log"]
include = []

Priority: CLI args > .hamidrezam.toml > global config (~/.config/hamidrezam/config.toml or ~/.hamidrezam.toml) > defaults.

Secrets policy

.env, .env.local/.production/.development/.staging, secrets.json, credentials.json (plus generic .env.*; .env.example is treated as a safe template). Default warn: included + listed as a warning. Use exclude to drop, include to silence the warning.

Large files

Any file over max_size (default 2GB; accepts 500MB, 1024, …) follows large_files.mode (default warn). Never silently dropped.

Git handling

.git/ excluded by default (include_git=false). Enable per-run (--include-git) or per-project ([git] include=true). .gitignore/.gitattributes are always preserved.

Restore

hamidrezam restore backup.zip ./restored-project --overwrite

Validates the archive, rejects ../ and absolute entries, confines writes to the destination, preserves structure, skips existing files unless --overwrite, restores symlinks best-effort (falls back to regular files on Windows without privilege).

Verification

Every backup auto-verifies (ZIP integrity + manifest schema). Re-check later:

hamidrezam verify backup.zip
hamidrezam verify backup.zip --check-hashes   # re-hash contents vs manifest

Each archive embeds .hamidrezam/manifest.json with tool, version, created_at, project_name, profiles, statistics, warnings, and per-file path/size/sha256/modified_time (relative paths only).

Security

• No blind extraction; all member names validated.
• Symlinks never followed outside the project; loops detected via (st_dev, st_ino).
• Broken links, special files (sockets/FIFOs/devices), permission errors → skipped with warnings, never fatal.
• Secrets/large files surface as warnings, never silently leaked/dropped.

Examples

• examples/.hamidrezam.toml — annotated config.
• examples/basic_backup.py — python examples/basic_backup.py after install.

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
python -m build

Testing

pytest            # full suite
pytest tests/unit
pytest tests/integration

Covers scanner (nesting/empty/unicode/spaces), exclusions, secrets, large files, ZIP+manifest+hashes, restore/overwrite/traversal, symlinks (broken/outside/skip), CLI exit codes, and the mandatory source-integrity test (hashes + paths + mtimes identical before/after backup).

Roadmap

• tar.gz writer (TarGzBackupWriter via the existing BackupWriter interface).
• Opt-in .gitignore-aware mode, negation (!) support.
• Progress bars, JSON output (--json), exclusion-size report table.
• hamidrezam init config generator.

Known limitations (0.1.0)

• Only zip format (--format tar.gz fails with a clear future-reserved message).
• .gitignore patterns are parsed by GitIgnoreRule for API use but not auto-applied to backups (avoids surprising drops of .env-style files).
• runs/, logs/, tmp/, temp/, outputs/, checkpoints/ directory names are excluded wherever they appear; rename intentional source dirs or use --include to keep them.
• Symlink restore on Windows may fall back to regular files without Developer Mode/admin.

License

MIT — see LICENSE.

Author

Hamidreza Moghaddam Kohi — Full Stack Developer · AI · Automation Website: https://hamidrezamoghaddam.ir/ · Email: info@hamidrezamoghaddam.ir