DIRCONV(1)

📦 in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 DIRCONV(1) — the dirconv page, but make it cute 💖

okay bestie, welcome to dirconv(1), the manual page for a lil utility called dirconv that goes hunting for weirdly-encoded file names and then fixes them for you. it's giving detective but for character encodings. 🕵️♀️✨

🌸 NAME 🌸

dirconv — locate and transcode mixed-encoding file names 💅

✨ SYNOPSIS ✨

dirconv [-078dFhnpruvw] [-f charset] [-x regex] [path ...]

🦋 DESCRIPTION 🦋

okay so here's the vibe. the dirconv utility recursively scans the path(s) you gave it and sorts every file and directory by what its name looks like:

  • pure 7-bit ASCII 💯
  • not ASCII, but valid UTF-8 🌈
  • double-UTF-8 (WTF-8) 😭
  • none of the above 🙈

names in that last category? we just assume they're Latin-1, unless you told us a different encoding with the -f option.

and then, by default, dirconv prints out the names that are neither pure 7-bit ASCII nor valid UTF-8. that's it. that's the default behavior. no cap.

the following options are available:

  • -0 — print a NUL character instead of a newline after each path. heads up tho: this option does nothing if you also used -n. ✋
  • -7 — select names that are pure 7-bit ASCII. 💯
  • -8 — select names that contain non-ASCII characters but are not valid UTF-8. this is the default unless you specified -7, -u and / or -w. 👀
  • -d — show debugging info. you can stack this option multiple times to crank up the level of detail. 📈
  • -F — paired with -r, force renaming a file when the target already exists. no fear. 🔥
  • -f charset — specify the assumed character set for non-ASCII, non-UTF-8 names. the default is “iso8859-1”. 🌍
  • -h — print a usage message and exit. classic. 👋
  • -n — paired with -r, show what would have happened, but don't actually rename any files. it's a dress rehearsal bestie, nothing gets touched. 🙈
  • -p — print the selected names. 🖨️
  • -r — attempt to convert the selected names to UTF-8 and rename the files and directories. the main character option. 👑
  • -u — select names which contain non-ASCII characters and are valid UTF-8 but not WTF-8. 🌈
  • -v — print the source reversion number and exit. ℹ️
  • -w — select names which seem to be WTF-8-encoded. 😭
  • -x regex — do not inspect files and directories whose unconverted names match the specified POSIX extended regular expression. 🚫

💜 SEE ALSO 💜

iconv(1), regex(3).

🎀 AUTHORS 🎀

the dirconv utility and this manual page were written by Dag-Erling Smørgrav <des@des.no> for the University of Oslo. absolute icons, honestly. 🫶

⭐ NOTES ⭐

okay so how does it even work? dirconv attempts to decode each name as if it were a sequence of UTF-8 characters. it is possible — but highly unlikely — that a random string of characters in a non-UTF single-byte encoding would look like a valid UTF-8 sequence. so like, don't panic, but also… it's a thing. 😅

reliable detection of WTF-8 is only possible if the original 8-bit encoding is known. periodt. 🔍

the exclusion filter is applied before name conversion. character classes are unlikely to work as expected on unconverted names. so don't come for me when your regex acts up bestie, i warned you. 💀

🫶 that's the whole page! this was dirconv(1), dated November 18, 2014, and yeah, the footer really does just say DIRCONV(1) again. slay. 💅✨🌸
📦 where this page comes from