1 .\" Under BSD, just give to nroff or troff (with -man).
2 .\" To print the MS-DOS version, use option -rO2.
3 .\" Under System V, take out the '.\" ' from the next line.
5 .TH MMV 1 "November 20, 2001 (v1.0lfs)"
8 mmv \- move/copy/append/link multiple files by wildcard patterns
12 mmv \- move/copy/append multiple files by wildcard patterns
24 .if '\nO'2' [\fB-m\fP|\fBx\fP|\fBr\fP|\fBc\fP|\fBo\fP|\fBa\fP|\fBz\fP]
25 .if '\nO'0' [\fB-m\fP|\fBx\fP|\fBr\fP|\fBc\fP|\fBo\fP|\fBa\fP|\fBl\fP|\fBs\fP]
26 .if '\nO'1' [\fB-m\fP|\fBx\fP|\fBr\fP|\fBc\fP|\fBo\fP|\fBa\fP|\fBl\fP]
41 .ie '\nO'2' or appends,
42 .el appends, or links,
44 each source file matching a
46 pattern to the target name specified by the
49 This multiple action is performed safely,
50 i.e. without any unexpected deletion of files
51 due to collisions of target names with existing filenames
52 or with other target names.
53 Furthermore, before doing anything,
55 attempts to detect any errors that would result
56 from the entire set of actions specified
57 and gives the user the choice of either
58 proceeding by avoiding the offending parts
60 .I mmv does support large files (LFS) but it does *NOT* support
61 sparse files (i.e. it explodes them).
68 .ie '\nO'2' or appends
70 is governed by the first set of options given
72 If none of these are specified,
74 a default (patchable by
80 the task is given by the command name under which
82 was invoked (argv[0]):
84 command name default task
95 The task option choices are:
98 move source file to target name.
99 Both must be on the same device.
100 Will not move directories.
102 If the source file is a symbolic link,
103 moves the link without checking if the link's target from the new
104 directory is different than the old.
108 same as -m, except cross-device moves are done
109 by copying, then deleting source.
110 When copying, sets the
111 .ie !'\nO'2' permission bits
113 and file modification time
114 of the target file to that of the source file.
117 rename source file or directory to target name.
118 The target name must not include a path:
119 the file remains in the same directory in all cases.
120 This option is the only way of renaming directories under
122 .if '\nO'2' It is only available under DOS version 3.0 or higher.
125 copy source file to target name.
126 Sets the file modification time and
127 .ie !'\nO'2' permission bits
129 of the target file to that of the source file,
130 regardless of whether the target file already exists.
131 Chains and cycles (to be explained below) are not allowed.
134 overwrite target name with source file.
136 If target file exists, its attributes are left unchanged.
137 If not, it is created with ordinary attributes
138 unrelated to the source file's attributes.
139 In either case, the file modification time is set to the current time.
142 If target file exists, it is overwritten,
143 keeping its original owner and permission bits.
144 If it does not exist, it is created, with read-write permission bits
147 and the execute permission bits copied from the source file.
148 In either case, the file modification time is set to the current time.
152 append contents of source file to target name.
153 Target file modification time is set to the current time.
154 If target file does not exist,
156 .ie '\nO'2' attributes
159 Unlike all other options, -a allows multiple source files to have the
160 same target name, e.g. "mmv -a
163 big" will append all ".c" files to "big".
164 Chains and cycles are also allowed, so "mmv -a f f" will double up "f".
168 same as -a, but if the target file exists, and its last character is a ^Z,
169 and the source file is not empty,
170 this ^Z is truncated before doing the append.
175 link target name to source file.
176 Both must be on the same device,
177 and the source must not be a directory.
178 Chains and cycles are not allowed.
182 same as -l, but use symbolic links instead of hard links.
183 For the resulting link to aim back at the source,
184 either the source name must begin with a '/',
185 or the target must reside in either the current or the source directory.
186 If none of these conditions are met, the link is refused.
187 However, source and target can reside on different devices,
188 and the source can be a directory.
192 Only one of these option may be given,
193 and it applies to all matching files.
194 Remaining options need not be given separately,
195 i.e. "mmv -mk" is allowed.
198 Multiple Pattern Pairs
204 pattern pairs may be specified by omitting
205 the pattern pair on the command line,
206 and entering them on the standard input,
208 (If a pattern pair is given on the command line,
209 the standard input is not read.)
220 would rename "a" to "b" and "c" to "d".
221 If a file can be matched to several of the given
226 pattern of the first matching pair is used.
237 would give the error message "a -> c : no match" because file "a"
239 was already matched by the first pattern pair.
242 The \fIFrom\fP Pattern
246 pattern is a filename
247 with embedded wildcards: '*', '?', '['...']',
252 The first three have their usual
254 meanings of, respectively,
255 matching any string of characters,
256 matching any single character,
257 and matching any one of a set of characters.
259 Between the '[' and ']', a range from character 'a' through character 'z'
260 is specified with "a-z".
261 The set of matching characters can be negated by inserting
264 will match any character but 'b' through 'e', '2' through '5', and '_'.
267 Unlike DOS wildcards,
268 all mmv wildcards (except for cases listed below)
269 can occur anywhere in the pattern,
270 whether preceding or following explicit characters or other wildcards.
271 For example, the pattern "*z\\foo.bar" will search
272 for files named "foo.bar" in all subdirectories whose names end in 'z'.
273 However, no wildcards can occur in the drive letter.
275 The character '.' is not matched by any of '*', '?', or '['...']'.
276 Thus, the pattern "*" will only match files with a null extension.
277 To save yourself some typing, use the '!' wildcard instead,
278 which matches the same as "*.*",
279 except it is assigned only one wildcard index (see below).
280 Thus, both "f!" and "f*.*"
281 will match all of "f", "f.ext", "foo", and "foo.ext",
282 while "f*" will match only the first and the third.
285 Note that paths are allowed in the patterns,
286 and wildcards may be intermingled with slashes arbitrarily.
288 is useful for matching files at any depth in the directory tree.
289 It matches the same as "*\*(SL" repeated any number of times, including zero,
290 and can only occur either at the beginning of the pattern
291 or following a '\*(SL'.
292 Thus ";*.c" will match all ".c" files in or below the current directory,
293 while "\*(SL;*.c" will match them anywhere on the file system.
302 begins with "~/", the '~' is replaced with the home directory name.
303 (Note that the "~user" feature of
306 However, the '~' is not treated as a wildcard,
307 in the sense that it is not assigned a wildcard index (see below).
310 Since matching a directory under a task option other than -r or -s
311 would result in an error,
312 tasks other than -r and -s
313 match directories only against completely explicit
315 patterns (i.e. not containing wildcards).
316 Under -r and -s, this applies only to "." and "..".
319 Hidden and system files are also only matched
320 against completely explicit
325 Files beginning with '.' are only matched against
327 patterns that begin with an explicit '.'.
329 However, if -h is specified, they are matched normally.
332 Warning: since the shell normally expands wildcards
333 before passing the command-line arguments to
335 it is usually necessary to enclose the command-line
347 pattern is a filename
351 where an index consists of the character '#'
352 followed by a string of digits.
353 When a source file matches a
356 a target name for the file is constructed out of the
359 replacing the wildcard indexes by the
360 actual characters that matched the referenced wildcards
364 pattern is "abc*.*" and the
366 pattern is "xyz#2.#1",
367 then "abc.txt" is targeted to "xyztxt.".
368 (The first '*' matched "", and the second matched "txt".)
369 Similarly, for the pattern pair ";*.[clp]" -> "#1#3\*(SL#2",
370 "foo1\*(SLfoo2\*(SLprog.c" is targeted to "foo1\*(SLfoo2\*(SLc\*(SLprog".
371 Note that there is no '\*(SL' following the "#1" in the
374 since the string matched by any ';' is always either empty
375 or ends in a '\*(SL'.
376 In this case, it matches "foo1\*(SLfoo2\*(SL".
379 To convert the string matched by a wildcard
380 to either lowercase or uppercase before embedding it in the target name,
381 insert 'l' or 'u', respectively,
382 between the '#' and the string of digits.
390 can begin with a "~/" (see above).
391 This does not necessitate enclosing the
393 pattern in quotes on the command line
396 expands the '~' in the exact same manner as
400 does not expand it at all).
403 For all task options other than -r, if the target name is a directory,
404 the real target name is formed by appending
405 a '\*(SL' followed by the last component
406 of the source file name.
407 For example, "mmv dir1\*(SLa dir2" will,
408 if "dir2" is indeed a directory, actually move "dir1\*(SLa" to "dir2\*(SLa".
409 However, if "dir2\*(SLa" already exists and is itself a directory,
410 this is considered an error.
412 To strip any character (e.g. '*', '?', or '#')
413 of its special meaning to
415 as when the actual replacement name must contain the character '#',
416 precede the special character with a
422 (and enclose the argument in quotes because of the shell).
424 This also works to terminate a wildcard index
425 when it has to be followed by a digit in the filename, e.g. "a#1\*(ES1".
430 A chain is a sequence of specified actions where the target name of
431 one action refers to the source file of another action.
440 specifies the chain "a" -> "b" -> "c".
441 A cycle is a chain where the last target name
442 refers back to the first source file,
445 detects chains and cycles regardless of the order in which
446 their constituent actions are actually given.
447 Where allowed, i.e. in moving, renaming, and appending files,
448 chains and cycles are handled gracefully, by performing them in the proper
450 Cycles are broken by first renaming one of the files to a temporary name
451 (or just remembering its original size when doing appends).
454 Collisions and Deletions
456 When any two or more matching files
458 .ie '\nO'2' moved or copied
459 .el moved, copied, or linked
460 to the same target filename,
462 detects the condition as an error before performing any actions.
465 checks if any of its actions will result
466 in the destruction of existing files.
467 If the -d (delete) option is specified,
468 all file deletions or overwrites are done silently.
469 Under -p (protect), all deletions or overwrites
470 (except those specified with "(*)" on the standard input, see below)
471 are treated as errors.
472 And if neither option is specified,
473 the user is queried about each deletion or overwrite separately.
475 .ie '\nO'2' "\\dev\\con"
477 is used for all interactive queries,
478 not the standard input.)
483 Whenever any error in the user's action specifications is detected,
484 an error message is given on the standard output,
487 proceeds to check the rest of the specified actions.
488 Once all errors are detected,
490 queries the user whether he wishes
491 to continue by avoiding the erroneous actions or to abort altogether.
492 This and all other queries may be avoided by specifying either the
493 -g (go) or -t (terminate) option.
494 The former will resolve all difficulties by avoiding the erroneous actions;
495 the latter will abort
497 if any errors are detected.
498 Specifying either of them defaults
500 to -p, unless -d is specified
502 Thus, -g and -t are most useful when running
504 in the background or in
506 when interactive queries are undesirable.
511 Once the actions to be performed are determined,
513 performs them silently,
514 unless either the -v (verbose) or -n (no-execute) option is specified.
517 to report each performed action
518 on the standard output as
522 Here, "a" and "b" would be replaced by the source and target names,
524 If the action deletes the old target,
525 a "(*)" is inserted after the the target name.
526 Also, the "->" symbol is modified when a cycle has to be broken:
527 the '>' is changed to a '^' on the action prior to which the old target
528 is renamed to a temporary,
529 and the '-' is changed to a '=' on the action where the temporary is used.
531 Under -n, none of the actions are performed,
532 but messages like the above are printed on the standard output
533 with the ": done." omitted.
535 The output generated by -n can (after editing, if desired)
538 on the standard input
548 ignores lines on the standard input that look
549 like its own error and "done" messages,
550 as well as all lines beginning with white space,
551 and will accept pattern pairs with or without the intervening "->"
552 (or "-^", "=>", or "=^").
553 Lines with "(*)" after the target pattern have the effect of enabling -d
554 for the files matching this pattern only,
555 so that such deletions are done silently.
559 one must remember to specify again the task option (if any)
560 originally used to generate it.
564 attempts to predict all mishaps prior to performing any specified actions,
565 accidents may happen.
568 does not check for adequate free space when copying.
569 Thus, despite all efforts,
570 it is still possible for an action to fail
571 after some others have already been done.
572 To make recovery as easy as possible,
574 reports which actions have already been done and
575 which are still to be performed
576 after such a failure occurs.
577 It then aborts, not attempting to do anything else.
578 Once the user has cleared up the problem,
579 he can feed this report back to
581 on the standard input
582 to have it complete the task.
583 (The user is queried for a file name to dump this report
584 if the standard output has not been redirected.)
590 You can customize a copy of
595 If you wish to change the default task option,
609 also determines the best way to uniquely identify directories.
612 is set to use a method that is guaranteed to work the same way
613 for all versions of DOS,
615 and unable to correctly handle drives
622 there is a method that is fast and correct,
623 but uses an undocumented DOS feature
624 that may not work properly under all versions of DOS.
625 (However, 2.0 and 3.3 are known to work.)
629 determine the best method to use on your system
630 at run-time since this is too slow.
631 The choice is left to
633 which determines if the fast method works,
634 but also allows you to return to the slow method.
638 exits with status 1 if it aborts before doing anything,
639 with status 2 if it aborts due to failure after completing some of the actions,
640 and with status 0 otherwise.
643 mv(1), cp(1), ln(1), umask(1)
651 If the search pattern is not quoted,
652 the shell expands the wildcards.
654 then (usually) gives some error message,
655 but can not determine that the lack of quotes is the cause.
658 To avoid difficulties in semantics and error checking,
660 refuses to move or create directories.