nym

README

nym

A simple and BLAZINGLY FAST (NO WAY 😲) CLI tool to rename files with generic names to a timestamped, fingerprint-based format without overwriting an existing path.

---

🤔 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. Flags must appear before file and directory arguments.

# 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 these changes? [y/N]: y
Done!

nym only renames regular files. Directory scans skip symbolic links and special files such as FIFOs, sockets, and devices; passing one explicitly is an error. Filesystem roots are rejected as inputs, and nym's own state directory is excluded from scans.

An input, discovery, hashing, or destination error aborts the complete plan before the first rename. Each rename uses the operating system's atomic no-replace operation, so a destination that appears after confirmation is not overwritten. Unsupported no-replace or durability semantics fail safely instead of falling back to a replacing rename.

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 latest 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 check fails, the complete batch is rejected before any file is renamed. The actual rename also uses an atomic no-replace operation, so a destination created after the plan is shown is left untouched and the operation stops. Files already renamed earlier in that operation remain available to nym --rollback.

4. What should I do if I ACCIDENTALLY renamed a bunch of files? Can I undo it?

Yep! nym remembers the latest rename operation. To undo it, run:

nym --rollback

It will show what is going to be restored and ask for confirmation. The same command also handles an interrupted rename. If something is missing or unsafe, nym stops without overwriting it and keeps the rollback information so you can fix the problem and try again.

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.

Documentation

Overview

Package main provides the nym command-line entrypoint.