nym

A simple and BLAZINGLY FAST (NO WAY 😲) CLI tool to rename files with generic names to a unique, timestamped, and content-hashed format.

---

🤔 What is this thing?

This is a simple and primitive program that I wrote for myself, but maybe it will be useful to you too.

Have you ever downloaded an image, say from Pinterest, and it has a generic name like image.jpg or download.png? Then you download another one, and it has the same name. This happens to me all the time. I'm too lazy to come up with a meaningful name for every little file, so I just smash the keyboard to get a unique name that won't conflict with others.

So, I wrote this tiny CLI tool in Go that automates the process. If this sounds like you, give it a try!

🚀 Installation

1. Pre-built Binaries (Recommended)

This is the fastest way. You don't even need to have Go installed on your system.

1. Go to the Releases page.
2. Download the archive for your operating system.
3. Extract the nym executable and move it to a directory in your system's PATH (e.g., /usr/local/bin on Linux/macOS).

2. Using `go install`

If you have Go installed (version 1.21 or later), you can install directly from the source:

go install github.com/kirinyoku/nym@latest

Note: Make sure your $GOPATH/bin is in your system's PATH to run the command from anywhere.

🛠️ Usage

Once nym is installed, you can use it on files or entire folders.

# Run on a single file
nym path/to/your/image.jpg

# Run on an entire folder
nym /path/to/your/downloads/

# Run on multiple files and folders at once
nym file1.png folder1/ file2.mp4

# Run on all files with the specified extension (e.g., .jpg)
nym *.jpg

The program will show you a plan and ask for your approval before making any changes.

- downloads/image.jpg
+ downloads/20260127_150405_a1b2c3d4e5f6.jpg

- downloads/image(1).jpg
+ downloads/20260127_150406_f7e6d5c4b3a2.jpg

Apply changes? [y/N]: y
Done!

Flags

Flag	Description	Default
-y	Skip the confirmation prompt and apply renames automatically.	false
-v	Enable verbose logging to see skipped files and other info.	false
-rollback	Undo the previous rename operation.	false

❓ FAQ

1. Why that weird filename format? (`YYYYMMDD_HHMMSS_.ext`)

I didn't want just a random string. This format is actually pretty useful:

• YYYYMMDD_HHMMSS_: This is the timestamp of when the file was last modified (in UTC). This is awesome because it means your files will automatically be sorted chronologically in your file explorer!
• <hash>: It's a short "fingerprint" (a 12-character snippet of a BLAKE3 hash). To balance speed and accuracy, the hash is generated differently based on file size. For small files, it's a hash of the entire content. For large files, it's a much faster hash derived from the file's start, end, and total size. This approach ensures great performance while making collisions extremely unlikely.
• .ext: The original file extension, preserved as-is.

2. Why do some of my renamed files not have an extension?

The program is simple and safe: it only keeps the extension that a file originally had.

• If you rename download.txt, the new file will end in .txt.
• If you rename a file named download (which has no extension), the new file will also have no extension.

It doesn't try to guess the file's type; it just preserves what's already there.

3. What happens if it tries to create a name that already exists? (Collisions)

The program is built to be safe. Before proposing any changes, it performs two crucial checks:

1. It checks if a file with the new name already exists on your disk.
2. It checks if two different files you're trying to process would end up with the same new name.

If either of these things happens, it will skip the problematic files to prevent ever overwriting your data. It will never delete or overwrite anything without your explicit "yes", and even then, it only performs the safe renames it has planned.

4. What should I do if I ACCIDENTALLY renamed all the files in the system? Can I undo it?

Yes, you can.

• After every successful rename operation, a log file named last_rename.json is saved to your system's cache directory (e.g., ~/.cache/nym/ on Linux).
• To undo your last operation, simply run nym --rollback.
• The program will show you a plan to revert the changes and ask for your confirmation. Once the rollback is complete, the log file is deleted.

5. Will it crash on my 30GB video file?

Nope! It's now extremely fast, even on huge files. To maximize performance, the program no longer reads the entire file if it's large. Instead, it cleverly generates a unique hash from the file's start, end, and size. This means it can process massive files in a fraction of a second without running out of memory.

6. What does nym mean?

nym comes from the Greek word -onym (name), as in the words synonym or pseudonym. Yes, it's stupid, I know, but you can always change the name of the binary to whatever you like.

---

❤️ Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

P.S. Again, this is a simple tool I built for my own workflow. If it helps you too, that's awesome. Feel free to tinker with the code.

---

Licensed under the MIT License. You can find it here.