9e1e5d38a614833b2a2dddd4c2cc18704334bac8
[pkg/mmv.git] / mmv.1
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.
4 .\" .nr O 1
5 .TH MMV 1 "November 20, 2001 (v1.0lfs)"
6 .ie !'\nO'2' \{\
7 .SH NAME
8 mmv \- move/copy/append/link multiple files by wildcard patterns
9 \}
10 .el \{
11 .SH NAME
12 mmv \- move/copy/append multiple files by wildcard patterns
13 \}
14 .ie '\nO'2' \{\
15 .ds SL \\\\
16 .ds ES '
17 \}
18 .el \{\
19 .ds SL /
20 .ds ES \\\\
21 \}
22 .SH SYNOPSIS
23 .B mmv
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]
27 [\fB\-h\fP]
28 [\fB\-d\fP|\fBp\fP]
29 [\fB\-g\fP|\fBt\fP]
30 [\fB\-v\fP|\fBn\fP]
31 [\fB\-\-\fP]
32 [\fBfrom to\fP]
33 .if '\nO'2' \{\
34 .br
35 .B mmvpatch
36 [\fBexecutable\fP]
37 \}
38 .SH "DESCRIPTION"
39 .I Mmv
40 moves (or copies,
41 .ie '\nO'2' or appends,
42 .el appends, or links,
43 as specified)
44 each source file matching a
45 .I from
46 pattern to the target name specified by the
47 .I to
48 pattern.
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,
54 .I mmv
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
59 or aborting.
60 .I mmv
61 does support large files (LFS) but it does *NOT* support 
62 sparse files (i.e. it explodes them).
63
64 .ce
65 The Task Options
66 .PP
67 Whether
68 .I mmv
69 moves, copies,
70 .ie '\nO'2' or appends
71 .el appends, or links
72 is governed by the first set of options given
73 above.
74 If none of these are specified,
75 .ie '\nO'2' \{\
76 a default (patchable by
77 .IR mmvpatch ,
78 and initially \-x)
79 determines the task.
80 \}
81 .el \{\
82 the task is given by the command name under which
83 .I mmv
84 was invoked (argv[0]):
85
86         command name    default task
87
88         mmv                     \-x
89 .br
90         mcp                     \-c
91 .br
92         mad                     \-a
93 .br
94         mln                     \-l
95 \}
96 .PP
97 The task option choices are:
98 .TP
99 \-m :
100 move source file to target name.
101 Both must be on the same device.
102 Will not move directories.
103 .if '\nO'0' \{\
104 If the source file is a symbolic link,
105 moves the link without checking if the link's target from the new
106 directory is different than the old.
107 \}
108 .TP
109 \-x :
110 same as \-m, except cross-device moves are done
111 by copying, then deleting source.
112 When copying, sets the
113 .ie !'\nO'2' permission bits
114 .el attributes
115 and file modification time
116 of the target file to that of the source file.
117 .TP
118 \-r :
119 rename source file or directory to target name.
120 The target name must not include a path:
121 the file remains in the same directory in all cases.
122 This option is the only way of renaming directories under
123 .IR mmv .
124 .if '\nO'2' It is only available under DOS version 3.0 or higher.
125 .TP
126 \-c :
127 copy source file to target name.
128 Sets the file modification time and
129 .ie !'\nO'2' permission bits
130 .el attributes
131 of the target file to that of the source file,
132 regardless of whether the target file already exists.
133 Chains and cycles (to be explained below) are not allowed.
134 .TP
135 \-o :
136 overwrite target name with source file.
137 .ie '\nO'2' \{\
138 If target file exists, its attributes are left unchanged.
139 If not, it is created with ordinary attributes
140 unrelated to the source file's attributes.
141 In either case, the file modification time is set to the current time.
142 \}
143 .el \{\
144 If target file exists, it is overwritten,
145 keeping its original owner and permission bits.
146 If it does not exist, it is created, with read-write permission bits
147 set according to
148 .IR umask (1),
149 and the execute permission bits copied from the source file.
150 In either case, the file modification time is set to the current time.
151 \}
152 .TP
153 \-a :
154 append contents of source file to target name.
155 Target file modification time is set to the current time.
156 If target file does not exist,
157 it is created with
158 .ie '\nO'2' attributes
159 .el permission bits
160 set as under \-o.
161 Unlike all other options, \-a allows multiple source files to have the
162 same target name, e.g. "mmv \-a
163 .ie '\nO'2' *.c
164 .el \\*.c
165 big" will append all ".c" files to "big".
166 Chains and cycles are also allowed, so "mmv \-a f f" will double up "f".
167 .ie '\nO'2' \{\
168 .TP
169 \-z :
170 same as \-a, but if the target file exists, and its last character is a ^Z,
171 and the source file is not empty,
172 this ^Z is truncated before doing the append.
173 \}
174 .el \{\
175 .TP
176 \-l :
177 link target name to source file.
178 Both must be on the same device,
179 and the source must not be a directory.
180 Chains and cycles are not allowed.
181 .if '\nO'0' \{\
182 .TP
183 \-s :
184 same as \-l, but use symbolic links instead of hard links.
185 For the resulting link to aim back at the source,
186 either the source name must begin with a '/',
187 or the target must reside in either the current or the source directory.
188 If none of these conditions are met, the link is refused.
189 However, source and target can reside on different devices,
190 and the source can be a directory.
191 \}
192 \}
193 .PP
194 Only one of these option may be given,
195 and it applies to all matching files.
196 Remaining options need not be given separately,
197 i.e. "mmv \-mk" is allowed.
198
199 .ce
200 Multiple Pattern Pairs
201 .PP
202 Multiple
203 .I from
204 --
205 .I to
206 pattern pairs may be specified by omitting
207 the pattern pair on the command line,
208 and entering them on the standard input,
209 one pair per line.
210 (If a pattern pair is given on the command line,
211 the standard input is not read.)
212 Thus,
213
214 .in +3
215 mmv
216 .br
217 a b
218 .br
219 c d
220 .in -3
221
222 would rename "a" to "b" and "c" to "d".
223 If a file can be matched to several of the given
224 .I from
225 patterns,
226 the
227 .I to
228 pattern of the first matching pair is used.
229 Thus,
230
231 .in +3
232 mmv
233 .br
234 a b
235 .br
236 a c
237 .in -3
238
239 would give the error message "a \-> c : no match" because file "a"
240 (even if it exists)
241 was already matched by the first pattern pair.
242
243 .ce
244 The \fIFrom\fP Pattern
245 .PP
246 The
247 .I from
248 pattern is a filename
249 with embedded wildcards: '*', '?', '['...']',
250 .if '\nO'2' \{\
251 \'!',
252 \}
253 and ';'.
254 The first three have their usual
255 .IR sh (1)
256 meanings of, respectively,
257 matching any string of characters,
258 matching any single character,
259 and matching any one of a set of characters.
260 .PP
261 Between the '[' and ']', a range from character 'a' through character 'z'
262 is specified with "a\-z".
263 The set of matching characters can be negated by inserting
264 a '^' after the '['.
265 Thus, "[^b\-e2\-5_]"
266 will match any character but 'b' through 'e', '2' through '5', and '_'.
267 .if '\nO'2' \{\
268 .PP
269 Unlike DOS wildcards,
270 all mmv wildcards (except for cases listed below)
271 can occur anywhere in the pattern,
272 whether preceding or following explicit characters or other wildcards.
273 For example, the pattern "*z\\foo.bar" will search
274 for files named "foo.bar" in all subdirectories whose names end in 'z'.
275 However, no wildcards can occur in the drive letter.
276 .PP
277 The character '.' is not matched by any of '*', '?', or '['...']'.
278 Thus, the pattern "*" will only match files with a null extension.
279 To save yourself some typing, use the '!' wildcard instead,
280 which matches the same as "*.*",
281 except it is assigned only one wildcard index (see below).
282 Thus, both "f!" and "f*.*"
283 will match all of "f", "f.ext", "foo", and "foo.ext",
284 while "f*" will match only the first and the third.
285 \}
286 .PP
287 Note that paths are allowed in the patterns,
288 and wildcards may be intermingled with slashes arbitrarily.
289 The ';' wildcard
290 is useful for matching files at any depth in the directory tree.
291 It matches the same as "*\*(SL" repeated any number of times, including zero,
292 and can only occur either at the beginning of the pattern
293 or following a '\*(SL'.
294 Thus ";*.c" will match all ".c" files in or below the current directory,
295 while "\*(SL;*.c" will match them anywhere on the file system.
296 .if !'\nO'2' \{\
297 .PP
298 In addition, if the
299 .I from
300 pattern
301 (or the
302 .I to
303 pattern)
304 begins with "~/", the '~' is replaced with the home directory name.
305 (Note that the "~user" feature of
306 .IR csh (1)
307 is not implemented.)
308 However, the '~' is not treated as a wildcard,
309 in the sense that it is not assigned a wildcard index (see below).
310 \}
311 .PP
312 Since matching a directory under a task option other than \-r or \-s
313 would result in an error,
314 tasks other than \-r and \-s
315 match directories only against completely explicit
316 .I from
317 patterns (i.e. not containing wildcards).
318 Under \-r and \-s, this applies only to "." and "..".
319 .PP
320 .ie '\nO'2' \{\
321 Hidden and system files are also only matched
322 against completely explicit
323 .I from
324 patterns.
325 \}
326 .el \{\
327 Files beginning with '.' are only matched against
328 .I from
329 patterns that begin with an explicit '.'.
330 \}
331 However, if \-h is specified, they are matched normally.
332 .if !'\nO'2' \{\
333 .PP
334 Warning: since the shell normally expands wildcards
335 before passing the command-line arguments to
336 .IR mmv ,
337 it is usually necessary to enclose the command-line
338 .I from
339 and
340 .I to
341 patterns in quotes.
342 \}
343
344 .ce
345 The \fITo\fP Pattern
346 .PP
347 The
348 .I to
349 pattern is a filename
350 with embedded
351 .I wildcard
352 .IR indexes ,
353 where an index consists of the character '#'
354 followed by a string of digits.
355 When a source file matches a
356 .I from
357 pattern,
358 a target name for the file is constructed out of the
359 .I to
360 pattern by
361 replacing the wildcard indexes by the
362 actual characters that matched the referenced wildcards
363 in the source name.
364 Thus, if the
365 .I from
366 pattern is "abc*.*" and the
367 .I to
368 pattern is "xyz#2.#1",
369 then "abc.txt" is targeted to "xyztxt.".
370 (The first '*' matched "", and the second matched "txt".)
371 Similarly, for the pattern pair ";*.[clp]" \-> "#1#3\*(SL#2",
372 "foo1\*(SLfoo2\*(SLprog.c" is targeted to "foo1\*(SLfoo2\*(SLc\*(SLprog".
373 Note that there is no '\*(SL' following the "#1" in the
374 .I to
375 pattern,
376 since the string matched by any ';' is always either empty
377 or ends in a '\*(SL'.
378 In this case, it matches "foo1\*(SLfoo2\*(SL".
379 .if !'\nO'2' \{\
380 .PP
381 To convert the string matched by a wildcard
382 to either lowercase or uppercase before embedding it in the target name,
383 insert 'l' or 'u', respectively,
384 between the '#' and the string of digits.
385 .PP
386 The
387 .I to
388 pattern,
389 like the
390 .I from
391 pattern,
392 can begin with a "~/" (see above).
393 This does not necessitate enclosing the
394 .I to
395 pattern in quotes on the command line
396 since
397 .IR csh (1)
398 expands the '~' in the exact same manner as
399 .I mmv
400 (or, in the case of
401 .IR sh (1),
402 does not expand it at all).
403 \}
404 .PP
405 For all task options other than \-r, if the target name is a directory,
406 the real target name is formed by appending
407 a '\*(SL' followed by the last component
408 of the source file name.
409 For example, "mmv dir1\*(SLa dir2" will,
410 if "dir2" is indeed a directory, actually move "dir1\*(SLa" to "dir2\*(SLa".
411 However, if "dir2\*(SLa" already exists and is itself a directory,
412 this is considered an error.
413 .PP
414 To strip any character (e.g. '*', '?', or '#')
415 of its special meaning to
416 .IR mmv ,
417 as when the actual replacement name must contain the character '#',
418 precede the special character with a
419 .ie '\nO'2' \{\
420 single quote (').
421 \}
422 .el \{\
423 \'\\'
424 (and enclose the argument in quotes because of the shell).
425 \}
426 This also works to terminate a wildcard index
427 when it has to be followed by a digit in the filename, e.g. "a#1\*(ES1".
428
429 .ce
430 Chains and Cycles
431 .PP
432 A chain is a sequence of specified actions where the target name of
433 one action refers to the source file of another action.
434 For example,
435
436 mmv
437 .br
438 a b
439 .br
440 b c
441
442 specifies the chain "a" \-> "b" \-> "c".
443 A cycle is a chain where the last target name
444 refers back to the first source file,
445 e.g. "mmv a a".
446 .I Mmv
447 detects chains and cycles regardless of the order in which
448 their constituent actions are actually given.
449 Where allowed, i.e. in moving, renaming, and appending files,
450 chains and cycles are handled gracefully, by performing them in the proper
451 order.
452 Cycles are broken by first renaming one of the files to a temporary name
453 (or just remembering its original size when doing appends).
454
455 .ce
456 Collisions and Deletions
457 .PP
458 When any two or more matching files
459 would have to be
460 .ie '\nO'2' moved or copied
461 .el moved, copied, or linked
462 to the same target filename,
463 .I mmv
464 detects the condition as an error before performing any actions.
465 Furthermore,
466 .I mmv
467 checks if any of its actions will result
468 in the destruction of existing files.
469 If the \-d (delete) option is specified,
470 all file deletions or overwrites are done silently.
471 Under \-p (protect), all deletions or overwrites
472 (except those specified with "(*)" on the standard input, see below)
473 are treated as errors.
474 And if neither option is specified,
475 the user is queried about each deletion or overwrite separately.
476 (A new stream to
477 .ie '\nO'2' "\\dev\\con"
478 .el "/dev/tty"
479 is used for all interactive queries,
480 not the standard input.)
481
482 .ce
483 Error Handling
484 .PP
485 Whenever any error in the user's action specifications is detected,
486 an error message is given on the standard output,
487 and
488 .I mmv
489 proceeds to check the rest of the specified actions.
490 Once all errors are detected,
491 .I mmv
492 queries the user whether he wishes
493 to continue by avoiding the erroneous actions or to abort altogether.
494 This and all other queries may be avoided by specifying either the
495 \-g (go) or \-t (terminate) option.
496 The former will resolve all difficulties by avoiding the erroneous actions;
497 the latter will abort
498 .I mmv
499 if any errors are detected.
500 Specifying either of them defaults
501 .I mmv
502 to \-p, unless \-d is specified
503 (see above).
504 Thus, \-g and \-t are most useful when running
505 .I mmv
506 in the background or in
507 a shell script,
508 when interactive queries are undesirable.
509
510 .ce
511 Reports
512 .PP
513 Once the actions to be performed are determined,
514 .I mmv
515 performs them silently,
516 unless either the \-v (verbose) or \-n (no-execute) option is specified.
517 The former causes
518 .I mmv
519 to report each performed action
520 on the standard output as
521
522 a \-> b : done.
523
524 Here, "a" and "b" would be replaced by the source and target names,
525 respectively.
526 If the action deletes the old target,
527 a "(*)" is inserted after the the target name.
528 Also, the "\->" symbol is modified when a cycle has to be broken:
529 the '>' is changed to a '^' on the action prior to which the old target
530 is renamed to a temporary,
531 and the '\-' is changed to a '=' on the action where the temporary is used.
532 .PP
533 Under \-n, none of the actions are performed,
534 but messages like the above are printed on the standard output
535 with the ": done." omitted.
536 .PP
537 The output generated by \-n can (after editing, if desired)
538 be fed back to
539 .I mmv
540 on the standard input
541 (by omitting the
542 .I from
543 --
544 .I to
545 pair on the
546 .I mmv
547 command line).
548 To facilitate this,
549 .I mmv
550 ignores lines on the standard input that look
551 like its own error and "done" messages,
552 as well as all lines beginning with white space,
553 and will accept pattern pairs with or without the intervening "\->"
554 (or "\-^", "=>", or "=^").
555 Lines with "(*)" after the target pattern have the effect of enabling \-d
556 for the files matching this pattern only,
557 so that such deletions are done silently.
558 When feeding
559 .I mmv
560 its own output,
561 one must remember to specify again the task option (if any)
562 originally used to generate it.
563 .PP
564 Although
565 .I mmv
566 attempts to predict all mishaps prior to performing any specified actions,
567 accidents may happen.
568 For example,
569 .I mmv
570 does not check for adequate free space when copying.
571 Thus, despite all efforts,
572 it is still possible for an action to fail
573 after some others have already been done.
574 To make recovery as easy as possible,
575 .I mmv
576 reports which actions have already been done and
577 which are still to be performed
578 after such a failure occurs.
579 It then aborts, not attempting to do anything else.
580 Once the user has cleared up the problem,
581 he can feed this report back to
582 .I mmv
583 on the standard input
584 to have it complete the task.
585 (The user is queried for a file name to dump this report
586 if the standard output has not been redirected.)
587 .if '\nO'2' \{\
588
589 .ce
590 \fIMmvpatch\fP
591 .PP
592 You can customize a copy of
593 .I mmv
594 via the
595 .I mmvpatch
596 utility.
597 If you wish to change the default task option,
598 run
599 .I mmvpatch
600 on a copy of
601 .I mmv
602 named as follows:
603
604         \-x, \-m, \-r           mmv.exe
605 .br
606         \-c, \-o                        mcp.exe
607 .br
608         \-a, \-z                        mad.exe
609 .PP
610 .I Mmvpatch
611 also determines the best way to uniquely identify directories.
612 As distributed,
613 .I mmv
614 is set to use a method that is guaranteed to work the same way
615 for all versions of DOS,
616 but is both slow
617 and unable to correctly handle drives
618 affected by the
619 .I join
620 and
621 .I subst
622 DOS commands.
623 Alternatively,
624 there is a method that is fast and correct,
625 but uses an undocumented DOS feature
626 that may not work properly under all versions of DOS.
627 (However, 2.0 and 3.3 are known to work.)
628 .I Mmv
629 does
630 .I not
631 determine the best method to use on your system
632 at run-time since this is too slow.
633 The choice is left to
634 .I mmvpatch,
635 which determines if the fast method works,
636 but also allows you to return to the slow method.
637 \}
638 .SH "EXIT STATUS"
639 .I Mmv
640 exits with status 1 if it aborts before doing anything,
641 with status 2 if it aborts due to failure after completing some of the actions,
642 and with status 0 otherwise.
643 .if !'\nO'2' \{\
644 .SH "SEE ALSO"
645 mv(1), cp(1), ln(1), umask(1)
646 \}
647 .SH "AUTHOR"
648 Vladimir Lanin
649 .br
650 lanin@csd2.nyu.edu
651 .SH "BUGS"
652 .if !'\nO'2' \{\
653 If the search pattern is not quoted,
654 the shell expands the wildcards.
655 .I Mmv
656 then (usually) gives some error message,
657 but can not determine that the lack of quotes is the cause.
658 .PP
659 \}\
660 To avoid difficulties in semantics and error checking,
661 .I mmv
662 refuses to move or create directories.