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