fhash

Hash your folder names with SHA-256, restore them anytime.
CLI · GUI · macOS Right-Click · Open Source

English | 中文

fhash replaces all subfolder names in a directory with short SHA-256 hashes (8 hex characters), while keeping a mapping file so you can restore the original names at any time.

Think of it as a reversible "anonymizer" for folder structures — useful for privacy, testing, or sharing project layouts without revealing sensitive names.

my_projects/                    my_projects/
├── 我的项目/          ──→      ├── 9ce557b3/
├── test_data/         ──→      ├── e7d87b73/
├── 2024年报告/         ──→      ├── 7c330497/
└── backend-api/       ──→      └── d753230e/

• SHA-256 hashing — 8-character hex hash per folder name (≈2.8 trillion combinations)
• Fully reversible — Restore original names from the mapping file at any time
• Idempotent — Running encode twice won't double-hash
• Collision-safe — Auto-extends hash length (8→9→10...) on collision
• Dry-run preview — See all changes before applying (--dry-run)
• Hidden folder aware — Skips . prefixed folders automatically
• Unicode support — Full CJK / emoji / Unicode folder name support
• Auto backup — Creates .bak before each operation
• macOS Right-Click — Native Finder Quick Actions (no third-party apps)
• GUI App — Cross-platform tkinter GUI, buildable as macOS .app and Windows .exe
• Zero dependencies — Pure Python stdlib (no pip install needed)

git clone https://github.com/zephyrq-z/fhash.git
cd fhash

# Install CLI to ~/bin/fhash
bash install.sh

# Install Finder right-click Quick Actions
bash install_quick_actions.sh

Requires Python 3.9+ — no pip packages needed.

git clone https://github.com/zephyrq-z/fhash.git
cd fhash
bash install.sh

# Or run directly without installing:
python3 fhash.py --help

git clone https://github.com/zephyrq-z/fhash.git
cd fhash
python3 fhash_gui.py

Download from Releases (coming soon).

After running bash install_quick_actions.sh:

1. Open Finder
2. Select a folder
3. Right-click → Quick Actions →
   • fhash Encode — Hash all subfolder names
   • fhash Decode — Restore original folder names
4. A notification will appear when done

Tip: If Quick Actions don't appear, go to System Settings → Privacy & Security → Extensions → Finder and enable fhash.

# Encode — hash all subfolder names
fhash encode /path/to/folder

# Preview only (dry-run, no changes)
fhash encode /path/to/folder --dry-run

# Decode — restore original names
fhash decode /path/to/folder

# List — view current mapping (read-only)
fhash list /path/to/folder

# Current directory (no path needed)
cd /path/to/folder && fhash encode

# Use -n to specify path
fhash encode -n /path/to/folder

# Skip confirmation prompt
fhash encode /path/to/folder --yes

$ fhash encode ~/projects --dry-run

Original Name                   →  Hashed Name
────────────────────────────── ─── ────────────
2024年报告                         →  7c330497
backend-api                     →  d753230e
test_data                       →  e7d87b73
我的项目                            →  9ce557b3

4 folder(s) will be renamed.

[dry-run] No changes made.

$ fhash decode ~/projects --yes

Hashed Name   →  Original Name
──────────── ─── ──────────────────────────────
7c330497      →  2024年报告
d753230e      →  backend-api
e7d87b73      →  test_data
9ce557b3      →  我的项目

✅ Done. 4 folder(s) restored to original names.

Launch the app and:

1. Select a folder — Click "Browse…" or paste a path
2. Preview — Click "👁 Preview Encode" to see what will change
3. Encode — Click "🔒 Encode" to hash folder names
4. Decode — Click "🔓 Decode" to restore original names
5. Refresh — Click "🔄 Refresh" to reload the folder list

Target Folder/
├── .folder_hash_map.json   ← Hidden mapping file (JSON)
├── a3f1b2c7/               ← Was "我的项目"
├── 8d4e2f01/               ← Was "test_data"
└── e7c93a12/               ← Was "2024年报告"

Mapping file (.folder_hash_map.json):

{
  "_meta": {
    "created": "2026-06-14T02:42:19.845934+00:00",
    "hash_algo": "sha256_8char"
  },
  "a3f1b2c7": "我的项目",
  "8d4e2f01": "test_data",
  "e7c93a12": "2024年报告"
}

Algorithm:

1. Compute SHA-256(folder_name) and take the first 8 hex characters
2. If a collision occurs, auto-extend to 9, 10, ... up to 64 characters
3. Rename each subfolder to its hash value
4. Store the hash → original_name mapping in .folder_hash_map.json
5. Hidden folders (. prefix) are always skipped
6. A .bak backup of the mapping file is created before each operation

git clone https://github.com/zephyrq-z/fhash.git
cd fhash
pip3 install pyinstaller pillow
bash build_mac.sh
# Output: dist/fhash.app

On a Windows machine with Python 3.9+:

git clone https://github.com/zephyrq-z/fhash.git
cd fhash
pip install pyinstaller pillow
build_win.bat
# Output: dist\fhash.exe

pip install pillow
python3 assets/gen_icon.py
# Generates assets/icon.icns (macOS) and assets/icon.ico (Windows)

fhash/
├── fhash.py                   # CLI tool (core logic)
├── fhash_gui.py               # GUI application (tkinter, cross-platform)
├── fhash-encode-runner.sh     # macOS Quick Action runner (encode)
├── fhash-decode-runner.sh     # macOS Quick Action runner (decode)
├── install.sh                 # CLI installer (symlink to ~/bin)
├── install_quick_actions.sh   # macOS Finder Quick Actions installer
├── build_mac.sh               # macOS .app builder (PyInstaller)
├── build_win.bat              # Windows .exe builder (PyInstaller)
├── assets/
│   ├── gen_icon.py            # App icon generator (Pillow)
│   ├── icon.icns              # macOS icon
│   └── icon.ico               # Windows icon
├── README.md                  # English docs (this file)
├── README.zh-CN.md            # 中文文档
├── LICENSE                    # MIT License
└── .gitignore

Issues and PRs are welcome! Here are some ideas for contributors:

• GUI drag-and-drop folder support
• Linux .AppImage / Nautilus right-click integration
• Windows Explorer right-click context menu (registry)
• Regex-based folder name filtering
• Password-encrypted mapping file option
• Batch mode for multiple directories
• Undo history (multi-level rollback)
• i18n: add more languages

MIT License — free for personal and commercial use.

Made with ❤️ by zephyrq-z