Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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]

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 cur-
       rent 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	direc-
       tory:

	  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 file-
       names  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  de-
	      vice.   Will not move directories.  If the source	file is	a sym-
	      bolic 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  directo-
	      ries 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 ex-
	      ists.  Chains and	cycles (to be explained	 below)	 are  not  al-
	      lowed.

       -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 per-
	      mission bits set according to umask(1), and the execute  permis-
	      sion 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 mod-
	      ification	 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  de-
	      vice, 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	condi-
	      tions are	met, the link is refused.  However, source and	target
	      can  reside on different devices,	and the	source can be a	direc-
	      tory.

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

       WARNING:	This operation mode does not work if the patterns itself  con-
       tain 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 sin-
       gle 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 in-
       termingled 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  oc-
       cur  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 up-
       percase before embedding	it in the target name, insert 'l' or 'u',  re-
       spectively, 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 man-
       ner 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	direc-
       tory, 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	 wild-
       card  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	grace-
       fully, by performing them in the	proper order.  Cycles  are  broken  by
       first  renaming one of the files	to a temporary name (or	just remember-
       ing 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 er-
       ror 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 in-
       put.)

				   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 er-
       roneous 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  ac-
       tions;  the latter will abort mmv if any	errors are detected.  Specify-
       ing 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 back-
       ground 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, re-
       spectively.  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 stan-
       dard 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 al-
       ready 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, 2001 (v1.0lfs)			MMV(1)

NAME | SYNOPSIS | EXAMPLES | DESCRIPTION | EXIT STATUS | SEE ALSO | AUTHOR | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mmv&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help