# ASCII names [Read the full manual →](https://books.dandaedre.com/manuals/ascii-names/) [Documentation](../README.md) · [Changelog](changelog.md) Application icon A small Rust application for cleaning filenames before using a folder on an ASCII-only computer. Run it on your modern computer while the USB drive is plugged in. It changes names in place; file contents are never opened or rewritten. ```sh cargo run --locked -p ascii-names ``` Drop a folder into the window (or use **Choose folder**). **Preview** lists proposed changes without writing anything. **Clean names** processes all files and subfolders. **Stop** stops between entries; completed renames remain in place. The window keeps the latest 200 messages. Drop one folder at a time. The selected folder itself keeps its name, so selecting a drive's mount point is safe. To clean a folder's own name too, select its parent. Symlinks and special files are skipped, including links to other folders. Hidden files are included. Nested mounted directories are treated as ordinary directories. ## Naming rules - Accented Latin letters lose their accents, including decomposed macOS accents: `Été.mov` → `Ete.mov`. Ligatures and common letters such as `œ`, `ß`, `ø`, `ł` become `oe`, `ss`, `o`, `l`. - Common Unicode quotes and dashes become ASCII punctuation. Other characters without a supported equivalent become `_`. This is not transliteration of every writing system: `日本.txt` becomes `__.txt`. - ASCII control characters and `<>:"/\|?*` become `_` for filesystem compatibility. Trailing dots/spaces are removed; empty names become `_`. Windows reserved names such as `CON.txt` gain an underscore prefix. - Names longer than 220 ASCII bytes are shortened, preserving short extensions. - Existing destinations are never overwritten or merged. Collisions receive `_1`, `_2`, etc., before a file's extension: `résumé.txt` becomes `resume_1.txt` when `resume.txt` already exists. Directories get the suffix at the end. Directories are handled inside out. Filesystem work runs on one worker, with 25 ms between rename attempts (at most about 40 renames per second). There are no parallel scans, content copies, or per-file flushes. Eject the USB drive normally afterward so the operating system finishes any buffered writes. Keep the selected tree idle while running. Names referenced by playlists, shortcuts, documents or projects are not updated inside those files. Preview first when these references matter. There is no automatic undo. Read/rename errors are reported and processing continues where possible; rerun after resolving the reported cause. A failed directory rename can leave already-cleaned children. ## Command line The same binary supports a folder argument, useful for terminal drag and drop: ```sh cargo run --locked -p ascii-names -- /path/to/folder --dry-run cargo run --locked -p ascii-names -- /path/to/folder cargo run --locked -p ascii-names -- /path/to/folder --delay-ms 100 ``` `--delay-ms` accepts 0–1000; the default is 25. Preview does not sleep. The CLI prints every change and a summary, and exits nonzero on errors. Preview paths show the traversal's intermediate paths before ancestor folders are renamed; preview is not a saved plan, and cleanup scans again. Build a standalone desktop binary with `cargo build --locked --release -p ascii-names`. For a smaller CLI-only build, add `--no-default-features`. No FFprobe or other external command is required. The desktop uses the same egui dependencies as the other Rust tools. Linux/macOS use an atomic no-replace rename and Windows uses MoveFileExW without replacement. Filesystems that do not support safe no-replace renames produce an error; the tool never falls back to an overwriting rename. The crate is included in workspace tests, Clippy, Rustdoc and coverage. Regression tests cover collisions, nested directories, previews, cancellation, pacing, symlinks, invalid UTF-8 filenames on Unix, and content preservation. ### FreeBSD CI hosts FreeBSD uses `renameat2` with `AT_RENAME_NOREPLACE` when available. The symbol is resolved at runtime, so older jail userlands (including FreeBSD 12) can still build, launch and preview. Actual cleanup on those systems returns an actionable unsupported-operation error without renaming anything. No overwriting fallback is used. The kernel, jail userland and filesystem must all support the operation. See the [FreeBSD API documentation change](https://lists.freebsd.org/archives/dev-commits-src-branches/2026-March/028297.html). On a FreeBSD jail whose libc lacks `renameat2`, the rename integration tests verify safe refusal and unchanged sources instead of executing their successful rename assertions; this limitation is printed in CI output. Preview and name conversion tests still run normally. Hosts exposing the API run the full rename tests; unexpected filesystem/permission/kernel errors still fail them. Successful renames and collision protection must also be tested on a supported host (Linux, macOS, Windows, or a FreeBSD installation with the API). Jenkins prints its OS version, and failing tests retain the underlying rename errors and CLI output.