Provided by: mmv_1.01b-19_amd64 bug

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)