Update README.md

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.
+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