Man page for multi

NAME

multi – bulk file rename/copy utility using Perl regexps

SYNOPSIS

multi [ -n | -q ] [ -r ] cmd perlfragment file [file...]
multi [ -n | -q ] [ -r ] - cmd cmd - perlfragment file [file...]

DESCRIPTION

multi is a utility which allows you to invoke a command (typically, but not always, mv or cp) on a lot of files in a complicated way.

The command-line arguments to multi include a command, a set of filenames, and a fragment of Perl. For each of the filenames, multi will use the fragment of Perl to transform the filename into a new filename, and will then invoke the given command, passing the old and new filenames as arguments.

multi is most often useful as a bulk rename or copy utility, by passing mv or cp as the command. However, it can have more complex uses as well; see the examples below.

ARGUMENTS

cmd

Provides the command to which pairs of filenames will eventually be passed. If this is just one word (typically cp or mv), you can simply supply that word on the command line.

A multiple-word command (such as ln -s or svn mv) can be used if you place it between two arguments containing only minus signs.

perlfragment

This fragment of Perl will be run for each file name you supply. The file name will be passed in in the special Perl variable $_, and the altered file name should be passed out in $_ as well. (Therefore, the simplest kind of Perl fragment you could use is a single s/// substitution command.)

All the Perl variable names used internally by multi itself begin with two underscore characters. Therefore, your Perl fragment can safely define its own variables (provided they do not begin with two underscores), without worrying about upsetting the functioning of multi.

files

After the Perl fragment, multi expects a list of file names to be transformed. Typically these will be generated by typing one or more wildcard expressions on the shell command line.

OPTIONS

By default, multi will print every command it executes on standard output, so that you can see what it has just done (in case it turns out to be wrong!).

Bourne-shell-style quoting is provided, so that copying the output of multi and pasting it into a shell script or on to a shell command line should work correctly.

-n

Do not actually execute the commands. Instead, only print them on standard output as they would be executed. (Useful for a dry run to make sure your Perl does what you meant it to do. When you've got it right, take off the -n option and let it run for real.)

-q

Only execute the commands, without printing them. (Useful for running within a larger script.)

By default, the two arguments passed to each invocation of the subcommand are the original filename and the transformed filename, in that order.

-r

Reverse the order of arguments to the subcommand, so that it receives the transformed file name before the original one.

EXAMPLES

The simplest use of multi is to rename a large number of files. Suppose, for example, you have a lot of text files with .txt extensions, and you prefer to use .text extensions:

$ multi mv 's/.txt$/.text/' *.txt
mv bar.txt bar.text
mv baz.txt baz.text
mv foo.txt foo.text

If you wanted to copy the files rather than moving them, the command becomes

$ multi cp 's/.txt$/.text/' *.txt
cp bar.txt bar.text
cp baz.txt baz.text
cp foo.txt foo.text

If you wanted to create symbolic links, you now need the command ln -s, which is composed of two words. So you need to tell multi where the command words stop and the Perl begins, using two single-dash arguments:

$ multi - ln -s - 's/.txt$/.text/' *.txt
ln -s bar.txt bar.text
ln -s baz.txt baz.text
ln -s foo.txt foo.text

Note that simply quoting the two-word command would not have worked, because multi would have assumed you genuinely meant a one-word command which had a space in the middle...

$ multi "ln -s" 's/.txt$/.text/' *.txt
'ln -s' bar.txt bar.text
'ln -s' baz.txt baz.text
'ln -s' foo.txt foo.text

... which was almost certainly not what you wanted!

The version control utility Subversion has a subcommand for moving files around within your working directory. However, it does not support wildcards, because svn mv expects to see precisely two arguments. So if you want to move a whole load of files into a subdirectory, a command such as svn mv win*.c windows will not work. multi comes to the rescue:

$ multi - svn mv - 's:^:windows/:' win*.c
svn mv winmain.c windows/winmain.c
svn mv winprint.c windows/winprint.c
svn mv winutils.c windows/winutils.c

Of course, your Perl fragment can be more complex than just a s/// command. Here's a means of tidying up after extracting an MS-DOS zip file containing all filenames in upper case:

$ multi mv 'y/A-Z/a-z/' *[A-Z]*
mv HEADER.H header.h
mv MAIN.C main.c
mv STUFF.C stuff.c

Here's an example using -r. Suppose you have lots of .wav sound files, and you want to encode them all into compressed Ogg Vorbis format. The oggenc command expects its destination file name as an argument to the -o parameter, so it's most convenient to put that before the input file name:

$ multi -r - oggenc -o - 's/.wav$/.ogg/' *.wav
oggenc -o bar.ogg bar.wav
oggenc -o baz.ogg baz.wav
oggenc -o foo.ogg foo.wav

Finally, here's a general technique for going beyond the limits of multi, in the case where you need to do something more ambitious with your two file names. Suppose you want to use one file name as the target of a shell redirection operator, for example.

$ multi - sh -c 'grep foo $0 > $1' - 's/.txt$/.grepped/' *.txt
sh -c 'grep foo $0 > $1' bar.txt bar.grepped
sh -c 'grep foo $0 > $1' baz.txt baz.grepped
sh -c 'grep foo $0 > $1' foo.txt foo.grepped

As each of these commands will be executed, the (explicitly invoked) shell will substitute the two filename arguments in place of $0 and $1, so that the effect will be that of running a set of commands like

grep foo bar.txt > bar.grepped
grep foo baz.txt > baz.grepped
grep foo foo.txt > foo.grepped

ACKNOWLEDGEMENTS

The O'Reilly book ‘Programming Perl’ includes a simple example script which contains the core idea of this program. It takes a single Perl argument followed by filenames, and invokes Perl's internal rename function. multi is a complete rewrite of this basic idea, supplying more options and configurability.

LICENCE

multi is free software, distributed under the MIT licence. Type multi --licence to see the full licence text.