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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
MMV(1)									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 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.

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

       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.

				  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
       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 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 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
       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 erro-
       neous 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 undesir-
       able.

				       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 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.   When	feeding	mmv its	own output, one	must remember to spec-
       ify 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 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)

NAME | SYNOPSIS | 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=SuSE+Linux%2fi386+11.3>

home | help