🧹 Filename Sanitizer

A Bash script to rename files in a directory by removing unsafe characters, handling name collisions, and ensuring consistent lowercase filenames.

🧩 Features

• Safe character handling: Removes all non-alphanumeric characters except underscores, hyphens, and periods
• Unicode cleanup: Converts special characters like ’, ？, （, ） to standard ASCII
• Collision avoidance: Adds numeric suffixes (_1, _2) to prevent overwriting
• Case normalization: Converts filenames to lowercase
• Space handling: Replaces spaces with underscores
• Truncation: Limits base filenames to 250 chars to stay under 255 char limit (filesystem safe)
• Dry-run support: Test changes before applying them

🚀 Usage

Fetch the script

curl -fsSL -o rename_safe.sh https://git.r21.io/primemover/rename_safe/raw/branch/master/rename_safe.sh

Make the script executable

chmod +x rename_safe.sh

Dry run (test mode)

./rename_safe.sh --dry-run /path/to/files

Actual renaming

./rename_safe.sh /path/to/files

Windows Users: Run this script in WSL or Git Bash - native Windows CMD/Powershell won't work

🧪 Test Script

Fetch the script

curl -fsSL -o test_rename.sh https://git.r21.io/primemover/rename_safe/raw/branch/master/test_rename.sh

Make the script executable

chmod +x test_rename.sh

Run validation tests

./test_rename.sh

Creates files with:

• Special characters (%, ’, !, (, ), ？)
• Multi-dot extensions (.en.vtt)
• Hidden files (.Hidden File)
• Long filenames (near 255 char limit)
• Duplicate filenames
• Mixed case names

⚙️ Configuration

Edit rename_safe.sh to customize:

• Max filename length: base_truncated="${sanitized_base:0:250}"
• Allowed characters: sed 's/[^a-zA-Z0-9._-]//g'
• Enable hidden file support: Uncomment .??* loop

⚠️ System-Specific Notes

📏 Filesystem Limitations

OS	Max Filename Length	Notes
Linux	255 bytes	UTF-8 encoded characters count as 1-4 bytes
Windows	260 characters	NTFS supports 32,767 characters (Unicode-aware)
macOS	255 characters	HFS+ and APFS both use 255 char limit

⚠️ This script truncates base names to 250 characters to allow room for extensions.
For extremely long extensions (e.g., .tar.gz), manual length checking may still be required.

🔧 Cross-Platform Compatibility

This script is compatible with:

• Linux (Debian, Ubuntu, Arch, etc.)
• macOS (requires GNU coreutils installed via Homebrew)
• WSL2 (Windows Subsystem for Linux)
• Git Bash (on Windows)

⚠️ Not Compatible With:

• Native Windows CMD/Powershell (due to mv, tr, sed differences)
• Legacy systems with non-Bash shells (e.g., sh or dash)

✅ Cross-Platform Tips

• Save scripts with LF line endings (not CRLF)
• Use dos2unix rename_safe.sh if editing on Windows
• Avoid filenames > 255 chars to ensure portability
• Test on target system before bulk renaming

📦 Example

Before:

"Let’s Play A Game!.en.vtt"
"401(k) Plan.en.vtt"
"VeryLongFilename_AAAA...AAA.txt"
"Duplicate Name"

After:

"lets_play_a_game.en.vtt"
"401k_plan.en.vtt"
"verylongfilename_aaaaa...aaa.txt"
"duplicate_name"
"duplicate_name_1"

📝 License

MIT License - see LICENSE for details