detox

Remove spaces and other undesirable characters from a file's name

$ detox [path/to/file]

$ detox [[-n|--dry-run]] -r [path/to/directory]

$ detox -r [path/to/directory]

detox [options] [file ...]

file ...
    One or more files or directories to process. If a directory is specified, detox will process its contents.

-r, --recursive
    Recursively process files in subdirectories.

-s <sequence>, --sequence=<sequence>
    Apply a specific character transformation sequence. Common sequences include safe, iso8859_1, utf_8.

-n, --dry-run
    Perform a dry run; show what operations would be performed without actually renaming any files.

-v, --verbose
    Display detailed information about each file being processed and its new name.

-c <config_file>
    Use an alternative configuration file instead of the default.

--special
    Also process special files (e.g., named pipes, device files) that are normally skipped.

-h, --help
    Display a help message and exit.

-V, --version
    Display version information and exit.

The detox command is a utility designed to clean up filenames, making them more compatible across various operating systems and filesystems. It achieves this by replacing or removing characters that are problematic or non-standard in Unix-like environments. These often include spaces, control characters, international characters (non-ASCII), and other special symbols that might cause issues in shell scripts, web servers, or when transferring files between different environments (e.g., Windows to Linux, or across different locales).

detox operates based on configurable sequences, which define the transformations applied to filenames. Common sequences include replacing spaces with underscores, converting filenames to lowercase, and handling Unicode characters by transliterating them to their closest ASCII equivalents or simply removing them if no equivalent exists. It supports recursive operation through directories and offers a dry-run mode to preview changes before execution, which is crucial given its file-modifying nature. Its primary goal is to ensure filenames are robust and easily manageable within a Unix-like environment.

Renaming files is a permanent and potentially destructive operation. Always use the -n (dry-run) option first to preview changes, especially on important data. Some character transformations, like transliteration or removal of non-ASCII characters, can lead to a loss of information or clarity in filenames. While detox attempts to avoid collisions, it's possible that two different original filenames might resolve to the same new filename after transformation, though detox is designed to handle this by appending suffixes.

detox uses configuration files (e.g., /etc/detoxrc or ~/.detoxrc) to define the transformation sequences. These files specify character mappings and rules for how problematic characters should be handled. This extensibility allows users to define custom cleaning rules tailored to specific needs.

Typical applications for detox include cleaning filenames of downloaded media files (e.g., movies, music) that often have spaces or special characters, preparing files for web servers or scripting environments where clean, predictable filenames are essential, and standardizing filenames across a large collection.

detox was created to address the common problem of "dirty" filenames, particularly those originating from Windows systems or web downloads which often contain spaces, special characters, or non-ASCII characters that can be problematic on Unix-like filesystems. Its development aimed to provide a robust and configurable solution for batch renaming, ensuring filenames are compatible and easily scriptable. It gained popularity among users who frequently deal with cross-platform file transfers or need to sanitize large collections of media files.

mv(1), rename(1), find(1), iconv(1)