Provided by: mmv_1.01b-19build1_amd64 
NAME
mmv - move/copy/append/link multiple files by wildcard patterns
SYNOPSIS
mmv [-m|x|r|c|o|a|l|s] [-h] [-d|p] [-g|t] [-v|n] [--] [from to]
EXAMPLES
Rename all *.jpeg files in the current directory to *.jpg:
mmv '*.jpeg' '#1.jpg'
Replace the first occurrence of abc with xyz in all files in the current directory:
mmv '*abc*' '#1xyz#2'
Rename files ending in .html.en, .html.de, etc. to ending in .en.html, .de.html, etc. in
the current directory:
mmv '*.html.??' '#1.#2#3.html'
Rename music files from <track no.> - <interpreter> - <song title>.ogg to <interpreter> -
<track no.> - <song title>.ogg in the current directory:
mmv '* - * - *.ogg' '#2 - #1 - #3.ogg'
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 filenames 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 directories 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 permission bits set according to umask(1), and the execute
permission 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 modification 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
conditions are met, the link is refused. However, source and target can reside on
different devices, and the source can be a directory.
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 / Reading Patterns from STDIN
Multiple from -- to pattern pairs may be specified by omitting the pattern 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 matching 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.
WARNING: This operation mode does not work if the patterns itself contain spaces. See
http://bugs.debian.org/149873 for details.
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 single 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 '#' followed by a string of digits. 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
targeted 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 manner 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 directory, 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
terminate 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
gracefully, by performing them in the proper order. Cycles are broken by first renaming
one of the files to a temporary name (or just remembering 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 erroneous 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 undesirable.
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 standard 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.
WARNING: This means that unexpected things may happen if files matched by the patterns
contain spaces. See http://bugs.debian.org/149873 for details.
When feeding mmv its own output, one must remember to specify 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 performed 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 ALSO
mv(1), cp(1), ln(1), umask(1)
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)