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]

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 pat-
       tern.  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.

								    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 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 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 wild-
       card 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 pattern 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  charac-
       ter  '#', 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#11".

								    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 mov-
       ing, 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  gener-
       ate 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 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, 1989 (v1.0)							    MMV(1)