chafn - Change File Names

chafn renames files using regular-expression-based pattern substitutions applied to the file names. It is a command-line tool that I've built and used on Linux and Windows.

The basic invocation is as follows:

% chafn [-debug] [-max substitutions]
        pattern replacement

where pattern is a regular expression to be matched in the file name(s) and replacement is the text to be substituted for the matched text. The default number of substitutions is 1. If you aren't sure of your regular expression, use the "-debug" option to show the results without actually renaming the files.

Escape sequences are allowed in pattern and are useful for matching non-ASCII characters:

\num - is replaced by a single character with the specified ASCII code; e.g., "\32" is replaced by the space character (" "), "\006" is replaced by the bell character, and "\0x7F" is replaced by the rubout character.
\char - is replaced by the specified character; e.g., "\\" is replaced by "\".

Each file argument on the command line is treated as a wildcard file specification and is internally matched against the files in the directory. If your command shell expands wildcards itself (e.g., on Unix), you might encounter a problem with single file names that contain regular expression characters. This occurs, for example, when a file name contains square brackets, "[]". If this happens, simply enclose the wildcard specification in single quotes to prevent the shell from expanding it: "chafn -lower '*.mp3'".


% chafn [-debug] [-Debug] [-help]
        [-all] [-max substitutions]
        [-capitalize] [-lower] [-upper] [-smart]
        [-change] [-dot] [-prefix text]
        [-swap extension] [-track number]
        [-underscores] [-yphen] [-Yphen]
        [pattern replacement]


puts the program in debug mode. In this mode, the program generates its usual output but does not rename the files. This is useful if you want to check beforehand that your invocation works the way you expect.
displays help information.
-max substitutions
specify the maximum number of substitutions to perform. The default maximum is 1 for the usual pattern/replacement substitutions. The "-all" option causes global replacement. For case conversions, the default is to apply the conversion globally to the file name; this can be altered by specifying the "-max" option after the case-conversion option.
causes the matched text to be capitalized, converted to lower-case, or converted to upper-case, respectively. The replacement text is automatically supplied internally and should not be specified on the command line. To perform case conversion on the whole file name, don't specify pattern. To perform case conversion only on matched text in the file name, specify pattern before one of these options.
converts "smart" UTF-8 code sequences and Microsoft characters into their normal ASCII equivalents. For example, left and right curly quotes are converted to straight ASCII quotes.
begins the new specification of a file name change. This option allows you to specify a file name change for one set of files and then a different file name change for another set of files. The option is followed by a name change specification (e.g., pattern and replacement text or other options) and the files to which the name change is to be applied. (There is an implied "-change" at the beginning of the command line.)
deletes dotted artist/album information from MP3 file names of the form, "track>. text - song.mp3". The ". text" part is removed, leaving "track - song.mp3".
-prefix text
inserts the text at the beginning of each file name. (This is just shorthand for the pattern, "^", and the replacement text, "text".)
-swap extension
swaps the second and third hyphen-separated fields in a file name. The file extension must include the period (".mp3" instead of just "mp3"). I frequently use this for music file names of the form:
    "track - artist - title.mp3"
The result is:
    "track - title - artist .mp3"
Notice the extra blank inserted before the file extension.
-track number
inserts a track number, separated by a hyphen, at the beginning of each file name. A leading zero is added for numbers less than ten. Examples: "01 - ", "02 - ", ..., "10 - ", "11 - ", etc.
replaces all underscores ("_") in a file name with spaces.
replaces the first space in a file name by " - " (space, 'yphen, space). For example, "01 Trams Of Old London.mp3" becomes "01 - Trams Of Old London.mp3".
replaces the first hyphen in a file name by " - " (space, hyphen, space). For example, "01-Toonerville Trolley.mp3" becomes "01 - Toonerville Trolley.mp3".
is a regular expression used to match the text to be replaced.
is the replacement text.
specifies the file(s) to be renamed.

Alex Measday  /  E-mail