Provided by: mmv_1.01b-15_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]

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

       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.

                                            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.  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)