MMV(1)                                                General Commands Manual                                                MMV(1)

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 colli‐
       sions 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 pro‐
       ceeding 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  multi‐
              ple  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  sepa‐
       rately, 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  pat‐
       tern pair.

       WARNING: This operation mode does not work if the patterns itself contain spaces.  See http://bugs.debian.org/149873 for de‐
       tails.

                                                             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 ap‐
       plies only to "." and "..".

       Files  beginning  with '.' are only matched against from patterns that begin with an explicit '.'.  However, if -h is speci‐
       fied, they are matched normally.

       Warning: since the shell normally expands wildcards before passing the command-line arguments to mmv, it is  usually  neces‐
       sary 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  pat‐
       tern  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  pat‐
       tern  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 direc‐
       tory, 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 con‐
       tain 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  perform‐
       ing 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 de‐
       struction 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 inter‐
       active queries are undesirable.

                                                                 Reports

       Once  the  actions to be performed are determined, mmv performs them silently, unless either the -v (verbose) or -n (no-exe‐
       cute) 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  in‐
       tervening  "->"  (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.de‐
       bian.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 com‐
       plete 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)

Usage: mmv [-m|x|r|c|o|a|l] [-h] [-d|p] [-g|t] [-v|n] [from to]

Use #[l|u]N in the ``to'' pattern to get the [lowercase|uppercase of the]
string matched by the N'th ``from'' pattern wildcard.

A ``from'' pattern containing wildcards should be quoted when given
on the command line. Also you may need to quote ``to'' pattern.

Use -- as the end of options.