A trivial series of coincidences led to me wanting to create a simple, Ruby based, copyfree licensed tool for changing the encodings used for filenames.


The executable command line utility cmv is simple enough to use. To change the names of all files in the current directory from UTF-8 to 8-bit ASCII, without any chance of a filename overwriting an existing file (including possibly multiple files being written to the same filename after transcoding filenames):

cmv -nf UTF-8 -t ASCII-8BIT *

The -n option is "noclobber" (thus using numbers at the ends of filenames to avoid files overwriting each other; default behavior simply overwrites existing files, just like mv would on standard Unix systems), the -f is "from" (the source encoding), and -t is "to" (the target encoding). The program tries to set sensible defaults for from and to, but they will both probably end up with the same encoding if you do not specify an encoding for at least one of the two.

If you are not sure how to specify an encoding, a list of supported encodings can be displayed with the -l option. It is likely to be long; you may want to pipe the output to a pager such as less, or narrow down the displayed output by piping it to a grep command.

Use the --help or -h option to learn more about how to use cmv.


Installing the Ruby programming language's runtime is a relatively simple operation, and a prerequisite for running cmv (because it is a Ruby project). The "standard" reference implementation of Ruby, often called MRI/YARV (for Matz' Ruby Implementation + Yet Another Ruby VM) is available in the default software management system of most open source Unix-like operating systems as well as Apple MacOS X. For users of Microsoft Windows, the RubyInstaller for Windows makes Ruby easy to install there, as well.

The normal way to install Ruby on most operating systems will also install the gems tool, which is a sort of software management system specific to Ruby tools, and is the way most Ruby libraries and applications are distributed, including cmv.

Once you have Ruby installed with rubygems, installing cmv should be easy. Just use the gem command:

$ gem install charset_move

You can also download the gem package from the FossRec project and use the gem command to build and install it:

$ gem build charset_move.gemspec
$ gem install charset_move-<version>.gem

In this example, replace <version> with the version number in the name of the gemfile you downloaded. For version 1.0.0, for instance, the command might look like this (though as of this writing it is not yet at version 1.0.0):

$ gem install charset_move-1.0.0.gem

Note that the $ character indicates your shell prompt, and is not part of the command. Depending on your setup, you may need to use sudo, log in as root, or engage in some other additional activities to ensure the gem is installed correctly. If you know of different requirements for installation on other systems, please feel free to submit patches or open an issue on the FossRec issue tracker.


This program was written by Chad Perrin, Copyright 2012. It can be redistributed under the terms of the Nietzsche Public License for now (see LICENSE file). This may change at some point -- probably to the Open Works License, which the NPL allows you to use in place of the NPL itself anyway.