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