nym

README

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

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

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

5. 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 a command-line utility to safely rename files based on their modification timestamp and content hash.

The goal is to transform generically named files like "photo.jpg" or "document.pdf" into a consistent, collision-resistant format: YYYYMMDD_HHMMSS_<hash>.ext. This is particularly useful for organizing collections of files, like downloads or photos, where original names are not descriptive and may cause conflicts.

How it works

1. Discovery: It recursively scans the files and directories provided as command-line arguments.
2. Processing: For each file, it calculates a new name in parallel using a pool of workers. The new name is composed of the file's modification time (in UTC) and the first 12 characters of its BLAKE3 hash. To optimize for speed, the hash is calculated differently depending on file size: for small files, it's a hash of the entire content; for large files, it's a hash of the file's beginning, end, and total size.
3. Validation: Before any changes are made, the program performs several crucial safety checks: - It ensures a file isn't being renamed to a path that already exists. - It detects if multiple source files would be renamed to the same destination path, preventing data loss from one file overwriting another.
4. Confirmation: It presents a clear plan of all proposed renames and prompts the user for confirmation before proceeding. This can be skipped with the -y flag.
5. Execution: If confirmed, it performs the file renames.

Usage

go run main.go [flags] <file_or_directory> [...]

Example:

nym ./downloads