MAN page from RedHat Other mmv-1.01b-3.i386.rpm

MMV

Section: User Commands (1)
Updated: November 20, 1989 (v1.0)
Index

NAME

mmv - move/copy/append/link multiple files by wildcard patterns

SYNOPSIS

mmv[-h][-d|p][-g|t][-v|n][from to]

DESCRIPTION

Mmvmoves (or copies,appends, or links,as specified)each source file matching afrompattern to the target name specified by thetopattern.This multiple action is performed safely,i.e. without any unexpected deletion of filesdue to collisions of target names with existing filenamesor with other target names.Furthermore, before doing anything,mmvattempts to detect any errors that would resultfrom the entire set of actions specifiedand gives the user the choice of eitherproceeding by avoiding the offending partsor aborting.

The Task Options

Whethermmvmoves, copies,appends, or linksis governed by the first set of options givenabove.If none of these are specified,the task is given by the command name under whichmmvwas 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.
-x :: same as -m, except cross-device moves are doneby copying, then deleting source.When copying, sets thepermission bitsand file modification timeof 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 undermmv.
-c :: copy source file to target name.Sets the file modification time andpermission bitsof 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 bitsset according toumask(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 withpermission bitsset as under -o.Unlike all other options, -a allows multiple source files to have thesame target name, e.g. "mmv -a\*.cbig" 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.

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

Multiplefrom--topattern pairs may be specified by omittingthe 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 givenfrompatterns,thetopattern 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

Thefrompattern is a filenamewith embedded wildcards: '*', '?', '['...']',and ';'.The first three have their usualsh(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 insertinga '^' 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 ';' wildcardis 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 patternor 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 thefrompattern(or thetopattern)begins with "~/", the '~' is replaced with the home directory name.(Note that the "~user" feature ofcsh(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 -swould result in an error,tasks other than -r and -smatch directories only against completely explicitfrompatterns (i.e. not containing wildcards).Under -r and -s, this applies only to "." and "..".

Files beginning with '.' are only matched againstfrompatterns that begin with an explicit '.'.However, if -h is specified, they are matched normally.

Warning: since the shell normally expands wildcardsbefore passing the command-line arguments tommv,it is usually necessary to enclose the command-linefrompatternin quotes.

The To Pattern

Thetopattern is a filenamewith embeddedwildcardindexes,where an index consists of the character '#'followed by a string of digits.When a source file matches afrompattern,a target name for the file is constructed out of thetopattern byreplacing the wildcard indexes by theactual characters that matched the referenced wildcardsin the source name.Thus, if thefrompattern is "abc*.*" and thetopattern 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 thetopattern,since the string matched by any ';' is always either emptyor ends in a '/'.In this case, it matches "foo1/foo2/".

To convert the string matched by a wildcardto either lowercase or uppercase before embedding it in the target name,insert 'l' or 'u', respectively,between the '#' and the string of digits.

Thetopattern,like thefrompattern,can begin with a "~/" (see above).This does not necessitate enclosing thetopattern in quotes on the command linesincecsh(1)expands the '~' in the exact same manner asmmv(or, in the case ofsh(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 appendinga '/' followed by the last componentof 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 tommv,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 indexwhen 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 ofone 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 namerefers back to the first source file,e.g. "mmv a a".Mmvdetects chains and cycles regardless of the order in whichtheir 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 properorder.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 fileswould have to bemoved, copied, or linkedto the same target filename,mmvdetects the condition as an error before performing any actions.Furthermore,mmvchecks if any of its actions will resultin 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,andmmvproceeds to check the rest of the specified actions.Once all errors are detected,mmvqueries the user whether he wishesto 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 abortmmvif any errors are detected.Specifying either of them defaultsmmvto -p, unless -d is specified(see above).Thus, -g and -t are most useful when runningmmvin the background or ina shell script,when interactive queries are undesirable.

Reports

Once the actions to be performed are determined,mmvperforms them silently,unless either the -v (verbose) or -n (no-execute) option is specified.The former causesmmvto report each performed actionon 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 targetis 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 outputwith the ": done." omitted.

The output generated by -n can (after editing, if desired)be fed back tommvon the standard input(by omitting thefrom--topair on themmvcommand line).To facilitate this,mmvignores lines on the standard input that looklike 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 -dfor the files matching this pattern only,so that such deletions are done silently.When feedingmmvits own output,one must remember to specify again the task option (if any)originally used to generate it.

Althoughmmvattempts to predict all mishaps prior to performing any specified actions,accidents may happen.For example,mmvdoes not check for adequate free space when copying.Thus, despite all efforts,it is still possible for an action to failafter some others have already been done.To make recovery as easy as possible,mmvreports which actions have already been done andwhich are still to be performedafter 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 tommvon the standard inputto have it complete the task.(The user is queried for a file name to dump this reportif the standard output has not been redirected.)

EXIT STATUS

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

AUTHOR

Vladimir Lanin
laninAATTcsd2.nyu.edu

BUGS

If the search pattern is not quoted,the shell expands the wildcards.Mmvthen (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,mmvrefuses to move or create directories.

This document was created byman2html,using the manual pages.

MMV