DETOX(1)

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
The detox utility renames files to make them easier to work with under Linux and other Unix-like operating systems. It replaces characters that make it hard to type out a filename with dashes and underscores. It also provides transcoding-based filters, converting ISO-8859-1 or CP-1252 to UTF-8. An additional filter unescapes CGI-escaped filenames.

  Sequences
detox is driven by a configurable series of filters, called a sequence. Sequences are covered in more detail in detoxrc(5) and are discoverable with the -L option. The default sequence will run the safe and wipeup filters. Other examples of pre-configured sequences are iso8859_1 and iso8859_1-legacy, which both provide transcoding to UTF-8, and then finish with the safe and wipeup filters.

  Options

-f configfile
    Use configfile instead of the default configuration files for loading translation sequences. No other config file will be parsed.

-h, --help
    Display helpful information.

--inline
    Run in inline mode. See inline-detox(1) for more details.

-L  List the currently available sequences. When paired with -v this option shows what filters are used in each sequence and any properties applied to the filters.

-n, --dry-run
    Doesn't actually change anything. This implies the -v option.

-r  Recurse into subdirectories. Any file or directory that starts with a period, such as .git/ or .cache/, will be ignored during recursion unless specified on the command line. Also, any file or directory specified in the ignore section of the config file will be ignored during recursion.

-s sequence
    Use sequence instead of default.

--special
    Works on special files (including links). Normally detox ignores these files. detox will not recurse into symlinks that point at directories.

-v  Be verbose about which files are being renamed.

-V  Show 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 is ignored.

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

detox -f my_detoxrc -L -v
    Will list the sequences within my_detoxrc, showing their filters and options.

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. These have special meaning within FreeBSD and Linux, and cause problems when you go to access them. I created detox to clean up these files.

Version 2.0 stepped back from transliteration out of the box, instead focusing on ease of use. Version 3.0 further shifted this, 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 this scenario is lossy and pointless.

AUTHORS
detox was written by Doug Harple.

CAVEATS
If, after the translation of a filename is finished, a file already exists with that same name, detox will not rename the file.