MAN page from OpenSuSE mmv-2.6-bp160.1.12.x86_64.rpm

MMV

Section: User Commands (1)
Updated: February 2024
Index

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

move/copy/link multiple files by wildcard patterns

The FROM pattern is a shell glob pattern, in which `*' stands for any numberof characters and `?' stands for a single character.

Use #[l|u]N in the TO pattern to get the string matched by the NthFROM pattern wildcard [lowercased|uppercased].

Patterns should be quoted on the command line.

--help: Print help and exit
-V, --version: Print version and exit
-h, --hidden: treat dot files normally (default=off)
-D, --makedirs: create non-existent directories (default=off)
-m, --move: move source file to target name
-x, --copydel: copy source to target, then delete source
-r, --rename: rename source to target in same directory
-c, --copy: copy source to target, preserving source permissions
-o, --overwrite: overwrite target with source, preserving target permissions
-l, --hardlink: link target name to source file
-s, --symlink: symlink target name to source file
-d, --force: perform file deletes and overwrites without confirmation
-p, --protect: treat file deletes and overwrites as errors
-g, --go: skip any erroneous actions
-t, --terminate: erroneous actions are treated as errors
-v, --verbose: report all actions performed
-n, --dryrun: only report which actions would be performed

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.mmvdoes support large files (LFS) but it does not supportsparse files (i.e. it explodes them).

Older versions ofmmvsupported interactive editing of the rename etc. operations, but using afragile system that could not cope with certain characters, such as spaces,in filenames. Users who require this functionality can useqmv(1)and friends (in therenameutilspackage).

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:

command name default task

        mmv                     --copydel

        mcp                     --copy

        mad                     --append

        mln                     --hardlink

The task option choices are:

--move:: move source file to target name.Both must be on the same device.If the source file is a symbolic link,moves the link without checking if the link's target from the newdirectory is different than the old.
--copydel:: same as --move, except cross-device moves are doneby copying, then deleting source.When copying, sets the permission bitsand file modification timeof the target file to that of the source file.
--rename:: 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.
--copy:: copy source file to target name.Sets the file modification time and permission 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.
--overwrite:: 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.
--append:: 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 bitsset as under --overwrite.Unlike all other options, --append allows multiple source files to have thesame 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".
--hardlink:: 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.
--symlink:: same as --hardlink, 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 options may be given,and it applies to all matching files.

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

The directories "." and ".." are only matched against completely explicitfrompatterns (i.e. not containing wildcards).

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-linefromandtopatterns in 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#1\1".

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 be moved, 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.(The terminal is used for interactive queries,not 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,mmvasks the user whether 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 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.

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.

EXAMPLES

Rename all*.jpegfiles in the current directory to*.jpg:

mmv '*.jpeg' '#1.jpg'

Replace the first occurrence ofabcwithxyzin all files in the current directory:

mmv '*abc*' '#1xyz#2'

Rename files ending in .html.en, .html.de, etc. to endingin .en.html, .de.html, etc. in the current directory:

mmv '*.html.??' '#1.#2#3.html'

Rename music files from<track no.> - <interpreter> - <song title>.oggto<interpreter> - <track no.> - <song title>.oggin the current directory:

mmv '* - * - *.ogg' '#2 - #1 - #3.ogg'

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

Written by Vladimir Lanin and Reuben Thomas.

BUGS

If the search pattern is not quoted,the shell expands the wildcards.Mmvthen (usually) gives some error message,but cannot determine that the lack of quotes is the cause.

To avoid difficulties in semantics and error checking,mmvrefuses to create directories.

COPYRIGHT

Copyright © 2023 Reuben Thomas <rrtAATTsc3d.org>.
Copyright © 1990 Vladimir Lanin.Licence GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.There is NO WARRANTY, to the extent permitted by law.

This document was created byman2html,using the manual pages.

MMV