↑ Software ↑


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 and Android and my Nintendo DS and ...

Invoking chafn without any arguments gives a brief list of the program's command-line options. Invoking it with the "-help" option results in more detailed usage information, including the syntax for regular expressions and substitution text. (The "-help" information is written to standard output, so it can be redirected to a file for future reference if desired.)

Command-line arguments are scanned left-to-right in one pass. When a non-option file name is encountered, the previously specified change options are applied to the file name. Consequently, you must specify options before the file names to which they apply.

When in doubt, verify the changes without making them using the "-test" ("-t") command-line option ... before the file names!

The basic invocation is as follows:

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

where pattern is a regular expression (syntax) to be matched in the file name(s) and replacement is the text to be substituted (syntax) for the matched text. The default number of substitutions is 1. If you aren't sure of your regular expression, use the "-test" 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 "\".


% chafn [-debug] [-test] [-help] [-glob]
        [-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/test mode. In either of these modes, the program does not rename the files. This is useful if you want to check beforehand that your invocation works the way you expect. In "-test" mode, the program generates the normal output. In "-debug" mode, the program generates additional debug messages.
displays help information.
If this option is specified — again, like "-test", before any file names — chafn will treat each file name on the command line as a possibly wildcard file specification. A directory scan for matching file names is performed internally and matched files are renamed. If "-glob" is not specified, chafn treats each file name as the name of a single file.
This option is intended for command shells that do not perform globbing before invoking a program, but I have have found it useful on rare occasions even in a UNIX shell. (Most recently, it was quicker and easier to let chafn match a problematic file name instead of painstakingly trying to get the shell to correctly package and pass the file name to chafn.)
-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