MMV(1)MMV(1)NAMEmmv - move/copy/append/link multiple files by wildcard patterns
SYNOPSISmmv [-m|x|r|c|o|a|l|s] [-h] [-d|p] [-g|t] [-v|n] [--] [from to]
DESCRIPTION
Mmv moves (or copies, appends, or links, as specified) each source file
matching a from pattern to the target name specified by the to pattern.
This multiple action is performed safely, i.e. without any unexpected
deletion of files due to collisions of target names with existing file‐
names or with other target names. Furthermore, before doing anything,
mmv attempts to detect any errors that would result from the entire set
of actions specified and gives the user the choice of either proceeding
by avoiding the offending parts or aborting. mmv does support large
files (LFS) but it does *NOT* support sparse files (i.e. it explodes
them).
The Task Options
Whether mmv moves, copies, appends, or links is governed by the first
set of options given above. If none of these are specified, the task
is given by the command name under which mmv was invoked (argv[0]):
command name default task
mmv-x
mcp -c
mad -a
mln -l
The task option choices are:
-m : move source file to target name. Both must be on the same
device. Will not move directories. If the source file is a
symbolic link, moves the link without checking if the link's
target from the new directory is different than the old.
-x : same as -m, except cross-device moves are done by copying, then
deleting source. When copying, sets the permission bits and
file modification time of the target file to that of the source
file.
-r : rename source file or directory to target name. The target name
must not include a path: the file remains in the same directory
in all cases. This option is the only way of renaming directo‐
ries under mmv.
-c : copy source file to target name. Sets the file modification
time and permission bits of the target file to that of the
source file, regardless of whether the target file already
exists. Chains and cycles (to be explained below) are not
allowed.
-o : overwrite target name with source file. If target file exists,
it is overwritten, keeping its original owner and permission
bits. If it does not exist, it is created, with read-write per‐
mission bits set according to umask(1), and the execute permis‐
sion bits copied from the source file. In either case, the file
modification time is set to the current time.
-a : append contents of source file to target name. Target file mod‐
ification time is set to the current time. If target file does
not exist, it is created with permission bits set as under -o.
Unlike all other options, -a allows multiple source files to
have the same target name, e.g. "mmv -a \*.c big" will append
all ".c" files to "big". Chains and cycles are also allowed, so
"mmv -a f f" will double up "f".
-l : link target name to source file. Both must be on the same
device, and the source must not be a directory. Chains and
cycles are not allowed.
-s : same as -l, but use symbolic links instead of hard links. For
the resulting link to aim back at the source, either the source
name must begin with a '/', or the target must reside in either
the current or the source directory. If none of these condi‐
tions are met, the link is refused. However, source and target
can reside on different devices, and the source can be a direc‐
tory.
Only one of these option may be given, and it applies to all matching
files. Remaining options need not be given separately, i.e. "mmv -mk"
is allowed.
Multiple Pattern Pairs
Multiple from -- to pattern pairs may be specified by omitting the pat‐
tern pair on the command line, and entering them on the standard input,
one pair per line. (If a pattern pair is given on the command line,
the standard input is not read.) Thus,
mmv
a b
c d
would rename "a" to "b" and "c" to "d". If a file can be matched to
several of the given from patterns, the to pattern of the first match‐
ing pair is used. Thus,
mmv
a b
a c
would give the error message "a -> c : no match" because file "a" (even
if it exists) was already matched by the first pattern pair.
The From Pattern
The from pattern is a filename with embedded wildcards: '*', '?',
'['...']', and ';'. The first three have their usual sh(1) meanings
of, respectively, matching any string of characters, matching any sin‐
gle character, and matching any one of a set of characters.
Between the '[' and ']', a range from character 'a' through character
'z' is specified with "a-z". The set of matching characters can be
negated by inserting a '^' after the '['. Thus, "[^b-e2-5_]" will
match any character but 'b' through 'e', '2' through '5', and '_'.
Note that paths are allowed in the patterns, and wildcards may be
intermingled with slashes arbitrarily. The ';' wildcard is useful for
matching files at any depth in the directory tree. It matches the same
as "*/" repeated any number of times, including zero, and can only
occur either at the beginning of the pattern or following a '/'. Thus
";*.c" will match all ".c" files in or below the current directory,
while "/;*.c" will match them anywhere on the file system.
In addition, if the from pattern (or the to pattern) begins with "~/",
the '~' is replaced with the home directory name. (Note that the
"~user" feature of csh(1) is not implemented.) However, the '~' is not
treated as a wildcard, in the sense that it is not assigned a wildcard
index (see below).
Since matching a directory under a task option other than -r or -s
would result in an error, tasks other than -r and -s match directories
only against completely explicit from patterns (i.e. not containing
wildcards). Under -r and -s, this applies only to "." and "..".
Files beginning with '.' are only matched against from patterns that
begin with an explicit '.'. However, if -h is specified, they are
matched normally.
Warning: since the shell normally expands wildcards before passing the
command-line arguments to mmv, it is usually necessary to enclose the
command-line from and to patterns in quotes.
The To Pattern
The to pattern is a filename with embedded wildcard indexes, where an
index consists of the character '#' or '=' followed by a string of dig‐
its. When a source file matches a from pattern, a target name for the
file is constructed out of the to pattern by replacing the wildcard
indexes by the actual characters that matched the referenced wildcards
in the source name. Thus, if the from pattern is "abc*.*" and the to
pattern is "xyz#2.#1", then "abc.txt" is targeted to "xyztxt.". (The
first '*' matched "", and the second matched "txt".) Similarly, for
the pattern pair ";*.[clp]" -> "#1#3/#2", "foo1/foo2/prog.c" is tar‐
geted to "foo1/foo2/c/prog". Note that there is no '/' following the
"#1" in the to pattern, since the string matched by any ';' is always
either empty or ends in a '/'. In this case, it matches "foo1/foo2/".
To convert the string matched by a wildcard to either lowercase or
uppercase before embedding it in the target name, insert 'l' or 'u',
respectively, between the '#' and the string of digits.
The to pattern, like the from pattern, can begin with a "~/" (see
above). This does not necessitate enclosing the to pattern in quotes
on the command line since csh(1) expands the '~' in the exact same man‐
ner as mmv (or, in the case of sh(1), does not expand it at all).
For all task options other than -r, if the target name is a directory,
the real target name is formed by appending a '/' followed by the last
component of the source file name. For example, "mmv dir1/a dir2"
will, if "dir2" is indeed a directory, actually move "dir1/a" to
"dir2/a". However, if "dir2/a" already exists and is itself a direc‐
tory, this is considered an error.
To strip any character (e.g. '*', '?', '#', or '=') of its special
meaning to mmv, as when the actual replacement name must contain the
character '#', precede the special character with a ´\' (and enclose
the argument in quotes because of the shell). This also works to ter‐
minate a wildcard index when it has to be followed by a digit in the
filename, e.g. "a#1\1".
Chains and Cycles
A chain is a sequence of specified actions where the target name of one
action refers to the source file of another action. For example,
mmv
a b
b c
specifies the chain "a" -> "b" -> "c". A cycle is a chain where the
last target name refers back to the first source file, e.g. "mmv a a".
Mmv detects chains and cycles regardless of the order in which their
constituent actions are actually given. Where allowed, i.e. in moving,
renaming, and appending files, chains and cycles are handled grace‐
fully, by performing them in the proper order. Cycles are broken by
first renaming one of the files to a temporary name (or just remember‐
ing its original size when doing appends).
Collisions and Deletions
When any two or more matching files would have to be moved, copied, or
linked to the same target filename, mmv detects the condition as an
error before performing any actions. Furthermore, mmv checks if any of
its actions will result in the destruction of existing files. If the
-d (delete) option is specified, all file deletions or overwrites are
done silently. Under -p (protect), all deletions or overwrites (except
those specified with "(*)" on the standard input, see below) are
treated as errors. And if neither option is specified, the user is
queried about each deletion or overwrite separately. (A new stream to
"/dev/tty" is used for all interactive queries, not the standard
input.)
Error Handling
Whenever any error in the user's action specifications is detected, an
error message is given on the standard output, and mmv proceeds to
check the rest of the specified actions. Once all errors are detected,
mmv queries the user whether he wishes to continue by avoiding the
erroneous actions or to abort altogether. This and all other queries
may be avoided by specifying either the -g (go) or -t (terminate)
option. The former will resolve all difficulties by avoiding the erro‐
neous actions; the latter will abort mmv if any errors are detected.
Specifying either of them defaults mmv to -p, unless -d is specified
(see above). Thus, -g and -t are most useful when running mmv in the
background or in a shell script, when interactive queries are undesir‐
able.
Reports
Once the actions to be performed are determined, mmv performs them
silently, unless either the -v (verbose) or -n (no-execute) option is
specified. The former causes mmv to report each performed action on
the standard output as
a -> b : done.
Here, "a" and "b" would be replaced by the source and target names,
respectively. If the action deletes the old target, a "(*)" is
inserted after the the target name. Also, the "->" symbol is modified
when a cycle has to be broken: the '>' is changed to a '^' on the
action prior to which the old target is renamed to a temporary, and the
'-' is changed to a '=' on the action where the temporary is used.
Under -n, none of the actions are performed, but messages like the
above are printed on the standard output with the ": done." omitted.
The output generated by -n can (after editing, if desired) be fed back
to mmv on the standard input (by omitting the from -- to pair on the
mmv command line). To facilitate this, mmv ignores lines on the stan‐
dard input that look like its own error and "done" messages, as well as
all lines beginning with white space, and will accept pattern pairs
with or without the intervening "->" (or "-^", "=>", or "=^"). Lines
with "(*)" after the target pattern have the effect of enabling -d for
the files matching this pattern only, so that such deletions are done
silently. When feeding mmv its own output, one must remember to spec‐
ify again the task option (if any) originally used to generate it.
Although mmv attempts to predict all mishaps prior to performing any
specified actions, accidents may happen. For example, mmv does not
check for adequate free space when copying. Thus, despite all efforts,
it is still possible for an action to fail after some others have
already been done. To make recovery as easy as possible, mmv reports
which actions have already been done and which are still to be per‐
formed after such a failure occurs. It then aborts, not attempting to
do anything else. Once the user has cleared up the problem, he can
feed this report back to mmv on the standard input to have it complete
the task. (The user is queried for a file name to dump this report if
the standard output has not been redirected.)
EXIT STATUS
Mmv exits with status 1 if it aborts before doing anything, with status
2 if it aborts due to failure after completing some of the actions, and
with status 0 otherwise.
SEE ALSOmv(1), cp(1), ln(1), umask(1)HISTORY
The original FreeBSD port of mmv was derived from the Usenet
comp.sources.unix postings <2438@litchi.bbn.com>,
<2439@litchi.bbn.com>, and <2643@litchi.bbn.com>. The current port is
based on the comp.binaries.ibm.pc postings (no messageids available).
The Unix version used '=' as the index escape character, while the MS-
DOS version used '#'. This port allows both.
AUTHOR
Vladimir Lanin
lanin@csd2.nyu.edu
BUGS
If the search pattern is not quoted, the shell expands the wildcards.
Mmv then (usually) gives some error message, but can not determine that
the lack of quotes is the cause.
To avoid difficulties in semantics and error checking, mmv refuses to
move or create directories.
November 20, 2001 (v1.0lfs) MMV(1)
