1MMV(1) General Commands Manual MMV(1)
2
6 mmv - move/copy/append/link multiple files by wildcard patterns
7
9 mmv [-m|x|r|c|o|a|l|s] [-h] [-d|p] [-g|t] [-v|n] [--] [from to]
10
12 Rename all *.jpeg files in the current directory to *.jpg:
13 mmv '*.jpeg' '#1.jpg'
15 Replace the first occurrence of abc with xyz in all files in the cur‐
17 rent directory:
18 mmv '*abc*' '#1xyz#2'
20 Rename files ending in .html.en, .html.de, etc. to ending in .en.html,
22 .de.html, etc. in the current directory:
23 mmv '*.html.??' '#1.#2#3.html'
25 Rename music files from <track no.> - <interpreter> - <song title>.ogg
27 to <interpreter> - <track no.> - <song title>.ogg in the current direc‐
28 tory:
29 mmv '* - * - *.ogg' '#2 - #1 - #3.ogg'
31
34 Mmv moves (or copies, appends, or links, as specified) each source file
35 matching a from pattern to the target name specified by the to pattern.
36 This multiple action is performed safely, i.e. without any unexpected
37 deletion of files due to collisions of target names with existing file‐
38 names or with other target names. Furthermore, before doing anything,
39 mmv attempts to detect any errors that would result from the entire set
40 of actions specified and gives the user the choice of either proceeding
41 by avoiding the offending parts or aborting. mmv does support large
42 files (LFS) but it does *NOT* support sparse files (i.e. it explodes
43 them).
44 The Task Options
46 Whether mmv moves, copies, appends, or links is governed by the first
48 set of options given above. If none of these are specified, the task
49 is given by the command name under which mmv was invoked (argv[0]):
50 command name default task
52 mmv -x
54 mcp -c
55 mad -a
56 mln -l
57 The task option choices are:
59 -m : move source file to target name. Both must be on the same
61 device. Will not move directories. If the source file is a
62 symbolic link, moves the link without checking if the link's
63 target from the new directory is different than the old.
64 -x : same as -m, except cross-device moves are done by copying, then
66 deleting source. When copying, sets the permission bits and
67 file modification time of the target file to that of the source
68 file.
69 -r : rename source file or directory to target name. The target name
71 must not include a path: the file remains in the same directory
72 in all cases. This option is the only way of renaming directo‐
73 ries under mmv.
74 -c : copy source file to target name. Sets the file modification
76 time and permission bits of the target file to that of the
77 source file, regardless of whether the target file already
78 exists. Chains and cycles (to be explained below) are not
79 allowed.
80 -o : overwrite target name with source file. If target file exists,
82 it is overwritten, keeping its original owner and permission
83 bits. If it does not exist, it is created, with read-write per‐
84 mission bits set according to umask(1), and the execute permis‐
85 sion bits copied from the source file. In either case, the file
86 modification time is set to the current time.
87 -a : append contents of source file to target name. Target file mod‐
89 ification time is set to the current time. If target file does
90 not exist, it is created with permission bits set as under -o.
91 Unlike all other options, -a allows multiple source files to
92 have the same target name, e.g. "mmv -a \*.c big" will append
93 all ".c" files to "big". Chains and cycles are also allowed, so
94 "mmv -a f f" will double up "f".
95 -l : link target name to source file. Both must be on the same
97 device, and the source must not be a directory. Chains and
98 cycles are not allowed.
99 -s : same as -l, but use symbolic links instead of hard links. For
101 the resulting link to aim back at the source, either the source
102 name must begin with a '/', or the target must reside in either
103 the current or the source directory. If none of these condi‐
104 tions are met, the link is refused. However, source and target
105 can reside on different devices, and the source can be a direc‐
106 tory.
107 Only one of these option may be given, and it applies to all matching
109 files. Remaining options need not be given separately, i.e. "mmv -mk"
110 is allowed.
111 Multiple Pattern Pairs / Reading Patterns from STDIN
113 Multiple from -- to pattern pairs may be specified by omitting the pat‐
115 tern pair on the command line, and entering them on the standard input,
116 one pair per line. (If a pattern pair is given on the command line,
117 the standard input is not read.) Thus,
118 mmv
120 a b
121 c d
122 would rename "a" to "b" and "c" to "d". If a file can be matched to
124 several of the given from patterns, the to pattern of the first match‐
125 ing pair is used. Thus,
126 mmv
128 a b
129 a c
130 would give the error message "a -> c : no match" because file "a" (even
132 if it exists) was already matched by the first pattern pair.
133 WARNING: This operation mode does not work if the patterns itself con‐
135 tain spaces. See http://bugs.debian.org/149873 for details.
136 The From Pattern
138 The from pattern is a filename with embedded wildcards: '*', '?',
140 '['...']', and ';'. The first three have their usual sh(1) meanings
141 of, respectively, matching any string of characters, matching any sin‐
142 gle character, and matching any one of a set of characters.
143 Between the '[' and ']', a range from character 'a' through character
145 'z' is specified with "a-z". The set of matching characters can be
146 negated by inserting a '^' after the '['. Thus, "[^b-e2-5_]" will
147 match any character but 'b' through 'e', '2' through '5', and '_'.
148 Note that paths are allowed in the patterns, and wildcards may be
150 intermingled with slashes arbitrarily. The ';' wildcard is useful for
151 matching files at any depth in the directory tree. It matches the same
152 as "*/" repeated any number of times, including zero, and can only
153 occur either at the beginning of the pattern or following a '/'. Thus
154 ";*.c" will match all ".c" files in or below the current directory,
155 while "/;*.c" will match them anywhere on the file system.
156 In addition, if the from pattern (or the to pattern) begins with "~/",
158 the '~' is replaced with the home directory name. (Note that the
159 "~user" feature of csh(1) is not implemented.) However, the '~' is not
160 treated as a wildcard, in the sense that it is not assigned a wildcard
161 index (see below).
162 Since matching a directory under a task option other than -r or -s
164 would result in an error, tasks other than -r and -s match directories
165 only against completely explicit from patterns (i.e. not containing
166 wildcards). Under -r and -s, this applies only to "." and "..".
167 Files beginning with '.' are only matched against from patterns that
169 begin with an explicit '.'. However, if -h is specified, they are
170 matched normally.
171 Warning: since the shell normally expands wildcards before passing the
173 command-line arguments to mmv, it is usually necessary to enclose the
174 command-line from and to patterns in quotes.
175 The To Pattern
177 The to pattern is a filename with embedded wildcard indexes, where an
179 index consists of the character '#' followed by a string of digits.
180 When a source file matches a from pattern, a target name for the file
181 is constructed out of the to pattern by replacing the wildcard indexes
182 by the actual characters that matched the referenced wildcards in the
183 source name. Thus, if the from pattern is "abc*.*" and the to pattern
184 is "xyz#2.#1", then "abc.txt" is targeted to "xyztxt.". (The first '*'
185 matched "", and the second matched "txt".) Similarly, for the pattern
186 pair ";*.[clp]" -> "#1#3/#2", "foo1/foo2/prog.c" is targeted to
187 "foo1/foo2/c/prog". Note that there is no '/' following the "#1" in
188 the to pattern, since the string matched by any ';' is always either
189 empty or ends in a '/'. In this case, it matches "foo1/foo2/".
190 To convert the string matched by a wildcard to either lowercase or
192 uppercase before embedding it in the target name, insert 'l' or 'u',
193 respectively, between the '#' and the string of digits.
194 The to pattern, like the from pattern, can begin with a "~/" (see
196 above). This does not necessitate enclosing the to pattern in quotes
197 on the command line since csh(1) expands the '~' in the exact same man‐
198 ner as mmv (or, in the case of sh(1), does not expand it at all).
199 For all task options other than -r, if the target name is a directory,
201 the real target name is formed by appending a '/' followed by the last
202 component of the source file name. For example, "mmv dir1/a dir2"
203 will, if "dir2" is indeed a directory, actually move "dir1/a" to
204 "dir2/a". However, if "dir2/a" already exists and is itself a direc‐
205 tory, this is considered an error.
206 To strip any character (e.g. '*', '?', or '#') of its special meaning
208 to mmv, as when the actual replacement name must contain the character
209 '#', precede the special character with a ´\' (and enclose the argument
210 in quotes because of the shell). This also works to terminate a wild‐
211 card index when it has to be followed by a digit in the filename, e.g.
212 "a#1\1".
213 Chains and Cycles
215 A chain is a sequence of specified actions where the target name of one
217 action refers to the source file of another action. For example,
218 mmv
220 a b
221 b c
222 specifies the chain "a" -> "b" -> "c". A cycle is a chain where the
224 last target name refers back to the first source file, e.g. "mmv a a".
225 Mmv detects chains and cycles regardless of the order in which their
226 constituent actions are actually given. Where allowed, i.e. in moving,
227 renaming, and appending files, chains and cycles are handled grace‐
228 fully, by performing them in the proper order. Cycles are broken by
229 first renaming one of the files to a temporary name (or just remember‐
230 ing its original size when doing appends).
231 Collisions and Deletions
233 When any two or more matching files would have to be moved, copied, or
235 linked to the same target filename, mmv detects the condition as an
236 error before performing any actions. Furthermore, mmv checks if any of
237 its actions will result in the destruction of existing files. If the
238 -d (delete) option is specified, all file deletions or overwrites are
239 done silently. Under -p (protect), all deletions or overwrites (except
240 those specified with "(*)" on the standard input, see below) are
241 treated as errors. And if neither option is specified, the user is
242 queried about each deletion or overwrite separately. (A new stream to
243 "/dev/tty" is used for all interactive queries, not the standard
244 input.)
245 Error Handling
247 Whenever any error in the user's action specifications is detected, an
249 error message is given on the standard output, and mmv proceeds to
250 check the rest of the specified actions. Once all errors are detected,
251 mmv queries the user whether he wishes to continue by avoiding the
252 erroneous actions or to abort altogether. This and all other queries
253 may be avoided by specifying either the -g (go) or -t (terminate)
254 option. The former will resolve all difficulties by avoiding the erro‐
255 neous actions; the latter will abort mmv if any errors are detected.
256 Specifying either of them defaults mmv to -p, unless -d is specified
257 (see above). Thus, -g and -t are most useful when running mmv in the
258 background or in a shell script, when interactive queries are undesir‐
259 able.
260 Reports
262 Once the actions to be performed are determined, mmv performs them
264 silently, unless either the -v (verbose) or -n (no-execute) option is
265 specified. The former causes mmv to report each performed action on
266 the standard output as
267 a -> b : done.
269 Here, "a" and "b" would be replaced by the source and target names,
271 respectively. If the action deletes the old target, a "(*)" is
272 inserted after the the target name. Also, the "->" symbol is modified
273 when a cycle has to be broken: the '>' is changed to a '^' on the
274 action prior to which the old target is renamed to a temporary, and the
275 '-' is changed to a '=' on the action where the temporary is used.
276 Under -n, none of the actions are performed, but messages like the
278 above are printed on the standard output with the ": done." omitted.
279 The output generated by -n can (after editing, if desired) be fed back
281 to mmv on the standard input (by omitting the from -- to pair on the
282 mmv command line). To facilitate this, mmv ignores lines on the stan‐
283 dard input that look like its own error and "done" messages, as well as
284 all lines beginning with white space, and will accept pattern pairs
285 with or without the intervening "->" (or "-^", "=>", or "=^"). Lines
286 with "(*)" after the target pattern have the effect of enabling -d for
287 the files matching this pattern only, so that such deletions are done
288 silently.
289 WARNING: This means that unexpected things may happen if files matched
291 by the patterns contain spaces. See http://bugs.debian.org/149873 for
292 details.
293 When feeding mmv its own output, one must remember to specify again the
295 task option (if any) originally used to generate it.
296 Although mmv attempts to predict all mishaps prior to performing any
298 specified actions, accidents may happen. For example, mmv does not
299 check for adequate free space when copying. Thus, despite all efforts,
300 it is still possible for an action to fail after some others have
301 already been done. To make recovery as easy as possible, mmv reports
302 which actions have already been done and which are still to be per‐
303 formed after such a failure occurs. It then aborts, not attempting to
304 do anything else. Once the user has cleared up the problem, he can
305 feed this report back to mmv on the standard input to have it complete
306 the task. (The user is queried for a file name to dump this report if
307 the standard output has not been redirected.)
308
310 Mmv exits with status 1 if it aborts before doing anything, with status
311 2 if it aborts due to failure after completing some of the actions, and
312 with status 0 otherwise.
313
315 mv(1), cp(1), ln(1), umask(1)
316
318 Vladimir Lanin
319 lanin@csd2.nyu.edu
320
322 If the search pattern is not quoted, the shell expands the wildcards.
323 Mmv then (usually) gives some error message, but can not determine that
324 the lack of quotes is the cause.
325 To avoid difficulties in semantics and error checking, mmv refuses to
327 move or create directories.
328 November 20, 2001 (v1.0lfs) MMV(1)