diff --git a/README.md b/README.md index a0a5f92..38de0b9 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,81 @@ -# rename_safe +# 🧹 Filename Sanitizer -A Bash script to rename files in a directory by removing unsafe characters, handling name collisions, and ensuring consistent lowercase filenames. \ No newline at end of file +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 +- **Dry-run support**: Test changes before applying them + +## 🚀 Usage + +```bash +# Clone the repo +git clone https://github.com/yourname/yourrepo.git +cd yourrepo + +# 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 +``` + +## 🧪 Test Script + +```bash +# 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 + +## ⚠️ Known Issues + +- Files with no extension will have suffixes appended directly +- Hidden file processing must be manually enabled +- Full path length is not checked (only basename) + +## 📦 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](LICENSE) for details \ No newline at end of file