beffroi-tools/docs/ascii-names/README.md

97 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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