1 \cfg{man-identity}{multi}{1}{2004-11-20}{Simon Tatham}{Simon Tatham}
3 \title Man page for \cw{multi}
7 \cw{multi} - bulk file rename/copy utility using Perl regexps
11 \c multi [ -n | -q ] [ -r ] cmd perlfragment file [file...]
12 \e bbbbb bb bb bb iii iiiiiiiiiiii iiii iiii
13 \c multi [ -n | -q ] [ -r ] - cmd cmd - perlfragment file [file...]
14 \e bbbbb bb bb bb iii iii iiiiiiiiiiii iiii iiii
18 \cw{multi} is a utility which allows you to invoke a command
19 (typically, but not always, \cw{mv} or \cw{cp}) on a lot of files in
22 The command-line arguments to \cw{multi} include a command, a set of
23 filenames, and a fragment of Perl. For each of the filenames,
24 \cw{multi} will use the fragment of Perl to transform the filename
25 into a new filename, and will then invoke the given command, passing
26 the old and new filenames as arguments.
28 \cw{multi} is most often useful as a bulk rename or copy utility, by
29 passing \cw{mv} or \cw{cp} as the command. However, it can have more
30 complex uses as well; see the examples below.
36 \dd Provides the command to which pairs of filenames will eventually
37 be passed. If this is just one word (typically \c{cp} or \c{mv}),
38 you can simply supply that word on the command line.
42 A multiple-word command (such as \c{ln -s} or \c{svn mv}) can be
43 used if you place it between two arguments containing only minus
50 \dd This fragment of Perl will be run for each file name you supply.
51 The file name will be passed in in the special Perl variable
52 \cw{$_}, and the altered file name should be passed out in \cw{$_}
53 as well. (Therefore, the simplest kind of Perl fragment you could
54 use is a single \cw{s///} substitution command.)
58 All the Perl variable names used internally by \cw{multi} itself
59 begin with two underscore characters. Therefore, your Perl fragment
60 can safely define its own variables (provided they do not begin with
61 two underscores), without worrying about upsetting the functioning
68 \dd After the Perl fragment, \cw{multi} expects a list of file names
69 to be transformed. Typically these will be generated by typing one
70 or more wildcard expressions on the shell command line.
74 By default, \cw{multi} will print every command it executes on
75 standard output, so that you can see what it has just done (in case
76 it turns out to be wrong!).
78 Bourne-shell-style quoting is provided, so that copying the output
79 of \cw{multi} and pasting it into a shell script or on to a shell
80 command line should work correctly.
84 \dd Do not actually execute the commands. Instead, \e{only} print
85 them on standard output as they would be executed. (Useful for a dry
86 run to make sure your Perl does what you meant it to do. When you've
87 got it right, take off the \cw{-n} option and let it run for real.)
91 \dd \e{Only} execute the commands, without printing them. (Useful
92 for running within a larger script.)
94 By default, the two arguments passed to each invocation of the
95 subcommand are the original filename and the transformed filename,
100 \dd Reverse the order of arguments to the subcommand, so that it
101 receives the transformed file name \e{before} the original one.
105 The simplest use of \cw{multi} is to rename a large number of files.
106 Suppose, for example, you have a lot of text files with \cw{.txt}
107 extensions, and you prefer to use \cw{.text} extensions:
109 \c $ multi mv 's/.txt$/.text/' *.txt
110 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
111 \c mv bar.txt bar.text
112 \c mv baz.txt baz.text
113 \c mv foo.txt foo.text
115 If you wanted to copy the files rather than moving them, the command
118 \c $ multi cp 's/.txt$/.text/' *.txt
119 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
120 \c cp bar.txt bar.text
121 \c cp baz.txt baz.text
122 \c cp foo.txt foo.text
124 If you wanted to create symbolic links, you now need the command
125 \cw{ln -s}, which is composed of two words. So you need to tell
126 \cw{multi} where the command words stop and the Perl begins, using
127 two single-dash arguments:
129 \c $ multi - ln -s - 's/.txt$/.text/' *.txt
130 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
131 \c ln -s bar.txt bar.text
132 \c ln -s baz.txt baz.text
133 \c ln -s foo.txt foo.text
135 Note that simply quoting the two-word command would not have worked,
136 because \cw{multi} would have assumed you genuinely meant a one-word
137 command which had a space in the middle...
139 \c $ multi "ln -s" 's/.txt$/.text/' *.txt
140 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
141 \c 'ln -s' bar.txt bar.text
142 \c 'ln -s' baz.txt baz.text
143 \c 'ln -s' foo.txt foo.text
145 ... which was almost certainly not what you wanted!
147 The version control utility \e{Subversion} has a subcommand for
148 moving files around within your working directory. However, it does
149 not support wildcards, because \cw{svn mv} expects to see
150 \e{precisely} two arguments. So if you want to move a whole load of
151 files into a subdirectory, a command such as \cw{svn mv win*.c
152 windows} will not work. \cw{multi} comes to the rescue:
154 \c $ multi - svn mv - 's:^:windows/:' win*.c
155 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
156 \c svn mv winmain.c windows/winmain.c
157 \c svn mv winprint.c windows/winprint.c
158 \c svn mv winutils.c windows/winutils.c
160 Of course, your Perl fragment can be more complex than just a
161 \cw{s///} command. Here's a means of tidying up after extracting an
162 MS-DOS zip file containing all filenames in upper case:
164 \c $ multi mv 'y/A-Z/a-z/' *[A-Z]*
165 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbb
166 \c mv HEADER.H header.h
168 \c mv STUFF.C stuff.c
170 Here's an example using \cw{-r}. Suppose you have lots of \c{.wav}
171 sound files, and you want to encode them all into compressed Ogg
172 Vorbis format. The \c{oggenc} command expects its destination file
173 name as an argument to the \c{-o} parameter, so it's most convenient
174 to put that \e{before} the input file name:
176 \c $ multi -r - oggenc -o - 's/.wav$/.ogg/' *.wav
177 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
178 \c oggenc -o bar.ogg bar.wav
179 \c oggenc -o baz.ogg baz.wav
180 \c oggenc -o foo.ogg foo.wav
182 Finally, here's a general technique for going beyond the limits of
183 \cw{multi}, in the case where you need to do something more
184 ambitious with your two file names. Suppose you want to use one file
185 name as the target of a shell redirection operator, for example.
187 \c $ multi - sh -c 'grep foo $0 > $1' - 's/.txt$/.grepped/' *.txt
188 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
189 \c sh -c 'grep foo $0 > $1' bar.txt bar.grepped
190 \c sh -c 'grep foo $0 > $1' baz.txt baz.grepped
191 \c sh -c 'grep foo $0 > $1' foo.txt foo.grepped
193 As each of these commands will be executed, the (explicitly invoked)
194 shell will substitute the two filename arguments in place of \cw{$0}
195 and \cw{$1}, so that the \e{effect} will be that of running a set of
198 \c grep foo bar.txt > bar.grepped
199 \c grep foo baz.txt > baz.grepped
200 \c grep foo foo.txt > foo.grepped
204 The O'Reilly book \q{Programming Perl} includes a simple example
205 script which contains the core idea of this program. It takes a
206 single Perl argument followed by filenames, and invokes Perl's
207 internal \cw{rename} function. \cw{multi} is a complete rewrite of
208 this basic idea, supplying more options and configurability.
212 \cw{multi} is free software, distributed under the MIT licence. Type
213 \cw{multi --licence} to see the full licence text.