1 \cfg{man-identity}{multi}{1}{2004-11-20}{Simon Tatham}{Simon Tatham}
4 \C{multi-manpage} Man page for \cw{multi}
6 \H{multi-manpage-name} NAME
8 \cw{multi} - bulk file rename/copy utility using Perl regexps
10 \H{multi-manpage-synopsis} SYNOPSIS
12 \c multi [ -n | -q ] [ -r ] cmd perlfragment file [file...]
13 \e bbbbb bb bb bb iii iiiiiiiiiiii iiii iiii
14 \c multi [ -n | -q ] [ -r ] - cmd cmd - perlfragment file [file...]
15 \e bbbbb bb bb bb iii iii iiiiiiiiiiii iiii iiii
17 \H{multi-manpage-description} DESCRIPTION
19 \cw{multi} is a utility which allows you to invoke a command
20 (typically, but not always, \cw{mv} or \cw{cp}) on a lot of files in
23 The command-line arguments to \cw{multi} include a command, a set of
24 filenames, and a fragment of Perl. for each of the filenames,
25 \cw{multi} will use the fragment of Perl to transform the filename
26 into a new filename, and will then invoke the given command, passing
27 the old and new filenames as arguments.
29 \cw{multi} is most often useful as a bulk rename or copy utility, by
30 passing \cw{mv} or \cw{cp} as the command. However, it can have more
31 complex uses as well; see the examples below.
33 \H{multi-manpage-args} ARGUMENTS
37 \dd Provides the command to which pairs of filenames will eventually
38 be passed. If this is just one word (typically \c{cp} or \c{mv}),
39 you can simply supply that word on the command line.
43 A multiple-word command (such as \c{ln -s} or \c{svn mv}) can be
44 used if you place it between two arguments containing only minus
51 \dd This fragment of Perl will be run for each file name you supply.
52 The file name will be passed in in the special Perl variable
53 \cw{$_}, and the altered file name should be passed out in \cw{$_}
54 as well. (Therefore, the simplest kind of Perl fragment you could
55 use is a single \cw{s///} substitution command.)
59 All the Perl variable names used internally by \cw{multi} itself
60 begin with two underscore characters. Therefore, your Perl fragment
61 can safely define its own variables (provided they do not begin with
62 two underscores), without worrying about upsetting the functioning
69 \dd After the Perl fragment, \cw{multi} expects a list of file names
70 to be transformed. Typically these will be generated by typing one
71 or more wildcard expressions on the shell command line.
73 \H{multi-manpage-options} OPTIONS
75 By default, \cw{multi} will print every command it executes on
76 standard output, so that you can see what it has just done (in case
77 it turns out to be wrong!).
79 Bourne-shell-style quoting is provided, so that copying the output
80 of \cw{multi} and pasting it into a shell script or on to a shell
81 command line should work correctly.
85 \dd Do not actually execute the commands. Instead, \e{only} print
86 them on standard output as they would be executed. (Useful for a dry
87 run to make sure your Perl does what you meant it to do. When you've
88 got it right, take off the \cw{-n} option and let it run for real.)
92 \dd \e{Only} execute the commands, without printing them. (Useful
93 for running within a larger script.)
95 By default, the two arguments passed to each invocation of the
96 subcommand are the original filename and the transformed filename,
101 \dd Reverse the order of arguments to the subcommand, so that it
102 receives the transformed file name \e{before} the original one.
104 \H{multi-manpage-examples} EXAMPLES
106 The simplest use of \cw{multi} is to rename a large number of files.
107 Suppose, for example, you have a lot of text files with \cw{.txt}
108 extensions, and you prefer to use \cw{.text} extensions:
110 \c $ multi mv 's/.txt$/.text/' *.txt
111 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
112 \c mv bar.txt bar.text
113 \c mv baz.txt baz.text
114 \c mv foo.txt foo.text
116 If you wanted to copy the files rather than moving them, the command
119 \c $ multi cp 's/.txt$/.text/' *.txt
120 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
121 \c cp bar.txt bar.text
122 \c cp baz.txt baz.text
123 \c cp foo.txt foo.text
125 If you wanted to create symbolic links, you now need the command
126 \cw{ln -s}, which is composed of two words. So you need to tell
127 \cw{multi} where the command words stop and the Perl begins, using
128 two single-dash arguments:
130 \c $ multi - ln -s - 's/.txt$/.text/' *.txt
131 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
132 \c ln -s bar.txt bar.text
133 \c ln -s baz.txt baz.text
134 \c ln -s foo.txt foo.text
136 Note that simply quoting the two-word command would not have worked,
137 because \cw{multi} would have assumed you genuinely meant a one-word
138 command which had a space in the middle...
140 \c $ multi "ln -s" 's/.txt$/.text/' *.txt
141 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
142 \c 'ln -s' bar.txt bar.text
143 \c 'ln -s' baz.txt baz.text
144 \c 'ln -s' foo.txt foo.text
146 ... which was almost certainly not what you wanted!
148 The version control utility \e{Subversion} has a subcommand for
149 moving files around within your working directory. However, it does
150 not support wildcards, because \cw{svn mv} expects to see
151 \e{precisely} two arguments. So if you want to move a whole load of
152 files into a subdirectory, a command such as \cw{svn mv win*.c
153 windows} will not work. \cw{multi} comes to the rescue:
155 \c $ multi - svn mv - 's:^:windows/:' win*.c
156 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
157 \c svn mv winmain.c windows/winmain.c
158 \c svn mv winprint.c windows/winprint.c
159 \c svn mv winutils.c windows/winutils.c
161 Of course, your Perl fragment can be more complex than just a
162 \cw{s///} command. Here's a means of tidying up after extracting a
163 MS-DOS zip file containing all filenames in upper case:
165 \c $ multi mv 'y/A-Z/a-z/' *[A-Z]*
166 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbb
167 \c mv HEADER.H header.h
169 \c mv STUFF.C stuff.c
171 Here's an example using \cw{-r}. Suppose you have lots of small C
172 programs and you want to quickly compile them all into binaries:
174 \c $ multi -r - cc -o - 's/.c$//' *.c
175 \c bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
180 Finally, here's a general technique for going beyond the limits of
181 \cw{multi}, in the case where you need to do something more
182 ambitious with your two file names. Suppose you want to use one file
183 name as the target of a shell redirection operator, for example.
185 \c $ multi - sh -c 'grep foo $0 > $1' - 's/.txt$/.grepped/' *.txt
186 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
187 \c sh -c 'grep foo $0 > $1' bar.txt bar.grepped
188 \c sh -c 'grep foo $0 > $1' baz.txt baz.grepped
189 \c sh -c 'grep foo $0 > $1' foo.txt foo.grepped
191 As each of these commands will be executed, the (explicitly invoked)
192 shell will substitute the two filename arguments in place of \cw{$0}
193 and \cw{$1}, so that the \e{effect} will be that of running a set of
196 \c grep foo bar.txt > bar.grepped
197 \c grep foo baz.txt > baz.grepped
198 \c grep foo foo.txt > foo.grepped
200 \H{multi-manpage-ack} ACKNOWLEDGEMENTS
202 The O'Reilly book \q{Programming Perl} includes a simple example
203 script which contains the core idea of this program. It takes a
204 single Perl argument followed by filenames, and invokes Perl's
205 internal \cw{rename} function. \cw{multi} is a complete rewrite of
206 this basic idea, supplying more options and configurability.
208 \H{multi-manpage-licence} LICENCE
210 \cw{multi} is free software, distributed under the MIT licence. Type
211 \cw{multi --licence} to see the full licence text.