DETOX(1)

💖 DETOX(1) — the glow-up your filenames have been waiting for 💖

okay bestie, so this is a General Commands Manual page, and today we're talking about detox. she cleans up filenames. that's it, that's the whole vibe, and honestly? she ate. ✨

---

✨ NAME ✨

detox — clean up filenames 🧼

---

🌸 SYNOPSIS 🌸

detox [-f configfile] [-n | --dry-run] [-r] [-s sequence] [--special]
      [-v] file ...
detox [-L] [-f configfile] [-v]
detox [-h | --help]
detox [-V]

---

🦋 DESCRIPTION 🦋

so detox is this utility that renames files so they're, like, actually pleasant to work with on Linux and other Unix-like operating systems. it takes the characters that make a filename a nightmare to type out and swaps them for dashes and underscores. slay. 💅

it also gives you transcoding-based filters, converting ISO-8859-1 or CP-1252 to UTF-8. and there's a bonus filter that unescapes CGI-escaped filenames, because of course there is. 🎀

🌈 Sequences 🌈

detox is driven by a configurable series of filters, and we call that a sequence. sequences get the full deep-dive treatment in detoxrc(5), and you can also just peek at what's available with the -L option. the default sequence runs the safe and wipeup filters. other pre-configured sequence examples include iso8859_1 and iso8859_1-legacy, and both of those transcode to UTF-8, then finish up with the safe and wipeup filters. iconic behavior, honestly. 👑

💜 Options 💜

• -f configfile — use configfile instead of the default configuration files for loading translation sequences. and no, no other config file will be parsed. it's configfile or nothing, periodt.
• -h, --help — shows you helpful information. bestie help, basically. 🫶
• --inline — runs in inline mode. check inline-detox(1) for the full tea. 🍓
• -L — lists the currently available sequences. and when you pair it with -v, it shows what filters each sequence uses plus any properties applied to those filters. the full receipts, no cap.
• -n, --dry-run — doesn't actually change anything. heads up: this implies the -v option. it's giving "let me think about it" energy and we respect that. 🙈
• -r — recurse into subdirectories. any file or directory that starts with a period, like .git/ or .cache/, gets ignored during recursion unless you specify it on the command line. also, anything listed in the ignore section of the config file gets ignored during recursion too. read the room, hidden files. 💀
• -s sequence — use sequence instead of default.
• --special — works on special files (including links). normally detox ignores those files entirely. but ngl, detox will not recurse into symlinks that point at directories. know the limits, queen.
• -v — be verbose about which files are being renamed. loud and proud. 📣
• -V — shows the current version of detox.

---

🎀 FILES 🎀

• /etc/detoxrc — the system-wide detoxrc file.
• ~/.detoxrc — a user's personal detoxrc. normally it extends the system-wide detoxrc, unless -f has been specified, in which case it's ignored. sorry babe, rules are rules.
• /usr/share/detox/cp1252.tbl — the provided CP-1252 transcoding table.
• /usr/share/detox/iso8859_1.tbl — the provided ISO-8859-1 transcoding table.
• /usr/share/detox/safe.tbl — the provided safe character translation table.
• /usr/share/detox/unicode.tbl — the provided Unicode control character filtering table, used by the UTF-8 filter.

---

⭐ EXAMPLES ⭐

detox -s lower -r -v -n /tmp/new_files

will run the sequence lower recursively, listing any changes, without changing anything, on the files of /tmp/new_files. a lil preview, a lil look, no commitment. 😌

detox -f my_detoxrc -L -v

will list the sequences within my_detoxrc, showing their filters and options. show me everything, bestie. 🔥

---

👑 SEE ALSO 👑

inline-detox(1), detox.tbl(5), detoxrc(5), ascii(7), iso_8859-1(7), unicode(7), utf-8(7)

---

💫 HISTORY 💫

detox was originally designed to clean up files that I had received from friends which had been created using other operating systems. it's trivial to create a filename with spaces, parenthesis, brackets, and ampersands under some operating systems. those have special meaning within FreeBSD and Linux, and they cause problems when you go to access them. so I created detox to clean up these files. a classic origin story, fr fr. 🌸

Version 2.0 stepped back from transliteration out of the box, and instead focused on ease of use. Version 3.0 shifted things even further by removing most of the transliteration from the tables. the primary motivations for this were user-provided feedback, and the fact that many modern Unix-like OSs use UTF-8 as their primary character set. transliterating from UTF-8 to ASCII in that scenario is lossy and pointless. and we don't do pointless here. 💅

---

🫶 AUTHORS 🫶

detox was written by Doug Harple. legend behavior.

---

💀 CAVEATS 💀

if, after the translation of a filename is finished, a file already exists with that same name, detox will not rename the file. so like… she's polite. she's not gonna overwrite your stuff. no chaos, no drama, just vibes. ✨

---

and that's the whole page, bestie!! this one came from Debian, dated March 31, 2024. go forth and let detox fix your filenames, you absolute icon. 💖🦋🌈