97 lines
5.2 KiB
Markdown
97 lines
5.2 KiB
Markdown
# ASCII names
|
||
|
||
[Read the full manual →](https://books.dandaedre.com/manuals/ascii-names/)
|
||
|
||
[Documentation](../README.md) · [Changelog](changelog.md)
|
||
|
||
<img src="../../crates/ascii-names/assets/app-icon.png" width="96" alt="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.
|