1MMV(1)                      General Commands Manual                     MMV(1)
2
3
4

NAME

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

SYNOPSIS

9       mmv [-m|x|r|c|o|a|l|s] [-h] [-d|p] [-g|t] [-v|n] [--] [from to]
10

EXAMPLES

12       Rename all *.jpeg files in the current directory to *.jpg:
13
14          mmv '*.jpeg' '#1.jpg'
15
16       Replace  the  first occurrence of abc with xyz in all files in the cur‐
17       rent directory:
18
19          mmv '*abc*' '#1xyz#2'
20
21       Rename files ending in .html.en, .html.de, etc. to ending in  .en.html,
22       .de.html, etc. in the current directory:
23
24          mmv '*.html.??' '#1.#2#3.html'
25
26       Rename  music files from <track no.> - <interpreter> - <song title>.ogg
27       to <interpreter> - <track no.> - <song title>.ogg in the current direc‐
28       tory:
29
30          mmv '* - * - *.ogg' '#2 - #1 - #3.ogg'
31
32

DESCRIPTION

34       Mmv moves (or copies, appends, or links, as specified) each source file
35       matching a from pattern to the target name specified by the to pattern.
36       This  multiple  action is performed safely, i.e. without any unexpected
37       deletion of files due to collisions of target names with existing file‐
38       names  or with other target names.  Furthermore, before doing anything,
39       mmv attempts to detect any errors that would result from the entire set
40       of actions specified and gives the user the choice of either proceeding
41       by avoiding the offending parts or aborting.  mmv  does  support  large
42       files  (LFS)  but  it does *NOT* support sparse files (i.e. it explodes
43       them).
44
45                                  The Task Options
46
47       Whether mmv moves, copies, appends, or links is governed by  the  first
48       set  of  options given above.  If none of these are specified, the task
49       is given by the command name under which mmv was invoked (argv[0]):
50
51            command name   default task
52
53            mmv            -x
54            mcp            -c
55            mad            -a
56            mln            -l
57
58       The task option choices are:
59
60       -m :   move source file to target name.   Both  must  be  on  the  same
61              device.   Will  not  move  directories.  If the source file is a
62              symbolic link, moves the link without  checking  if  the  link's
63              target from the new directory is different than the old.
64
65       -x :   same  as -m, except cross-device moves are done by copying, then
66              deleting source.  When copying, sets  the  permission  bits  and
67              file  modification time of the target file to that of the source
68              file.
69
70       -r :   rename source file or directory to target name.  The target name
71              must  not include a path: the file remains in the same directory
72              in all cases.  This option is the only way of renaming  directo‐
73              ries under mmv.
74
75       -c :   copy  source  file  to  target name.  Sets the file modification
76              time and permission bits of the  target  file  to  that  of  the
77              source  file,  regardless  of  whether  the  target file already
78              exists.  Chains and cycles  (to  be  explained  below)  are  not
79              allowed.
80
81       -o :   overwrite  target name with source file.  If target file exists,
82              it is overwritten, keeping its  original  owner  and  permission
83              bits.  If it does not exist, it is created, with read-write per‐
84              mission bits set according to umask(1), and the execute  permis‐
85              sion bits copied from the source file.  In either case, the file
86              modification time is set to the current time.
87
88       -a :   append contents of source file to target name.  Target file mod‐
89              ification  time is set to the current time.  If target file does
90              not exist, it is created with permission bits set as  under  -o.
91              Unlike  all  other  options,  -a allows multiple source files to
92              have the same target name, e.g. "mmv -a \*.c  big"  will  append
93              all ".c" files to "big".  Chains and cycles are also allowed, so
94              "mmv -a f f" will double up "f".
95
96       -l :   link target name to source file.   Both  must  be  on  the  same
97              device,  and  the  source  must  not be a directory.  Chains and
98              cycles are not allowed.
99
100       -s :   same as -l, but use symbolic links instead of hard  links.   For
101              the  resulting link to aim back at the source, either the source
102              name must begin with a '/', or the target must reside in  either
103              the  current  or  the source directory.  If none of these condi‐
104              tions are met, the link is refused.  However, source and  target
105              can  reside on different devices, and the source can be a direc‐
106              tory.
107
108       Only one of these option may be given, and it applies to  all  matching
109       files.   Remaining options need not be given separately, i.e. "mmv -mk"
110       is allowed.
111
112                Multiple Pattern Pairs / Reading Patterns from STDIN
113
114       Multiple from -- to pattern pairs may be specified by omitting the pat‐
115       tern pair on the command line, and entering them on the standard input,
116       one pair per line.  (If a pattern pair is given on  the  command  line,
117       the standard input is not read.)  Thus,
118
119          mmv
120          a b
121          c d
122
123       would  rename  "a"  to "b" and "c" to "d".  If a file can be matched to
124       several of the given from patterns, the to pattern of the first  match‐
125       ing pair is used.  Thus,
126
127          mmv
128          a b
129          a c
130
131       would give the error message "a -> c : no match" because file "a" (even
132       if it exists) was already matched by the first pattern pair.
133
134       WARNING: This operation mode does not work if the patterns itself  con‐
135       tain spaces.  See http://bugs.debian.org/149873 for details.
136
137                                  The From Pattern
138
139       The  from  pattern  is  a  filename  with embedded wildcards: '*', '?',
140       '['...']', and ';'.  The first three have their  usual  sh(1)  meanings
141       of,  respectively, matching any string of characters, matching any sin‐
142       gle character, and matching any one of a set of characters.
143
144       Between the '[' and ']', a range from character 'a'  through  character
145       'z'  is  specified  with  "a-z".  The set of matching characters can be
146       negated by inserting a '^' after  the  '['.   Thus,  "[^b-e2-5_]"  will
147       match any character but 'b' through 'e', '2' through '5', and '_'.
148
149       Note  that  paths  are  allowed  in  the patterns, and wildcards may be
150       intermingled with slashes arbitrarily.  The ';' wildcard is useful  for
151       matching files at any depth in the directory tree.  It matches the same
152       as "*/" repeated any number of times,  including  zero,  and  can  only
153       occur  either at the beginning of the pattern or following a '/'.  Thus
154       ";*.c" will match all ".c" files in or  below  the  current  directory,
155       while "/;*.c" will match them anywhere on the file system.
156
157       In  addition, if the from pattern (or the to pattern) begins with "~/",
158       the '~' is replaced with the  home  directory  name.   (Note  that  the
159       "~user" feature of csh(1) is not implemented.)  However, the '~' is not
160       treated as a wildcard, in the sense that it is not assigned a  wildcard
161       index (see below).
162
163       Since  matching  a  directory  under  a task option other than -r or -s
164       would result in an error, tasks other than -r and -s match  directories
165       only  against  completely  explicit  from patterns (i.e. not containing
166       wildcards).  Under -r and -s, this applies only to "." and "..".
167
168       Files beginning with '.' are only matched against  from  patterns  that
169       begin  with  an  explicit  '.'.   However, if -h is specified, they are
170       matched normally.
171
172       Warning: since the shell normally expands wildcards before passing  the
173       command-line  arguments  to mmv, it is usually necessary to enclose the
174       command-line from and to patterns in quotes.
175
176                                   The To Pattern
177
178       The to pattern is a filename with embedded wildcard indexes,  where  an
179       index  consists  of  the  character '#' followed by a string of digits.
180       When a source file matches a from pattern, a target name for  the  file
181       is  constructed out of the to pattern by replacing the wildcard indexes
182       by the actual characters that matched the referenced wildcards  in  the
183       source  name.  Thus, if the from pattern is "abc*.*" and the to pattern
184       is "xyz#2.#1", then "abc.txt" is targeted to "xyztxt.".  (The first '*'
185       matched  "", and the second matched "txt".)  Similarly, for the pattern
186       pair  ";*.[clp]"  ->  "#1#3/#2",  "foo1/foo2/prog.c"  is  targeted   to
187       "foo1/foo2/c/prog".   Note  that  there is no '/' following the "#1" in
188       the to pattern, since the string matched by any ';'  is  always  either
189       empty or ends in a '/'.  In this case, it matches "foo1/foo2/".
190
191       To  convert  the  string  matched  by a wildcard to either lowercase or
192       uppercase before embedding it in the target name, insert  'l'  or  'u',
193       respectively, between the '#' and the string of digits.
194
195       The  to  pattern,  like  the  from  pattern, can begin with a "~/" (see
196       above).  This does not necessitate enclosing the to pattern  in  quotes
197       on the command line since csh(1) expands the '~' in the exact same man‐
198       ner as mmv (or, in the case of sh(1), does not expand it at all).
199
200       For all task options other than -r, if the target name is a  directory,
201       the  real target name is formed by appending a '/' followed by the last
202       component of the source file name.   For  example,  "mmv  dir1/a  dir2"
203       will,  if  "dir2"  is  indeed  a  directory,  actually move "dir1/a" to
204       "dir2/a".  However, if "dir2/a" already exists and is itself  a  direc‐
205       tory, this is considered an error.
206
207       To  strip  any character (e.g. '*', '?', or '#') of its special meaning
208       to mmv, as when the actual replacement name must contain the  character
209       '#', precede the special character with a ´\' (and enclose the argument
210       in quotes because of the shell).  This also works to terminate a  wild‐
211       card  index when it has to be followed by a digit in the filename, e.g.
212       "a#1\1".
213
214                                  Chains and Cycles
215
216       A chain is a sequence of specified actions where the target name of one
217       action refers to the source file of another action.  For example,
218
219       mmv
220       a b
221       b c
222
223       specifies  the  chain  "a" -> "b" -> "c".  A cycle is a chain where the
224       last target name refers back to the first source file, e.g. "mmv a  a".
225       Mmv  detects  chains  and cycles regardless of the order in which their
226       constituent actions are actually given.  Where allowed, i.e. in moving,
227       renaming,  and  appending  files,  chains and cycles are handled grace‐
228       fully, by performing them in the proper order.  Cycles  are  broken  by
229       first  renaming one of the files to a temporary name (or just remember‐
230       ing its original size when doing appends).
231
232                              Collisions and Deletions
233
234       When any two or more matching files would have to be moved, copied,  or
235       linked  to  the  same  target filename, mmv detects the condition as an
236       error before performing any actions.  Furthermore, mmv checks if any of
237       its  actions  will result in the destruction of existing files.  If the
238       -d (delete) option is specified, all file deletions or  overwrites  are
239       done silently.  Under -p (protect), all deletions or overwrites (except
240       those specified with "(*)"  on  the  standard  input,  see  below)  are
241       treated  as  errors.   And  if neither option is specified, the user is
242       queried about each deletion or overwrite separately.  (A new stream  to
243       "/dev/tty"  is  used  for  all  interactive  queries,  not the standard
244       input.)
245
246                                   Error Handling
247
248       Whenever any error in the user's action specifications is detected,  an
249       error  message  is  given  on  the standard output, and mmv proceeds to
250       check the rest of the specified actions.  Once all errors are detected,
251       mmv  queries  the  user  whether  he wishes to continue by avoiding the
252       erroneous actions or to abort altogether.  This and all  other  queries
253       may  be  avoided  by  specifying  either  the -g (go) or -t (terminate)
254       option.  The former will resolve all difficulties by avoiding the erro‐
255       neous  actions;  the  latter will abort mmv if any errors are detected.
256       Specifying either of them defaults mmv to -p, unless  -d  is  specified
257       (see  above).   Thus, -g and -t are most useful when running mmv in the
258       background or in a shell script, when interactive queries are  undesir‐
259       able.
260
261                                       Reports
262
263       Once  the  actions  to  be  performed are determined, mmv performs them
264       silently, unless either the -v (verbose) or -n (no-execute)  option  is
265       specified.   The  former  causes mmv to report each performed action on
266       the standard output as
267
268       a -> b : done.
269
270       Here, "a" and "b" would be replaced by the  source  and  target  names,
271       respectively.   If  the  action  deletes  the  old  target,  a "(*)" is
272       inserted after the the target name.  Also, the "->" symbol is  modified
273       when  a  cycle  has  to  be  broken: the '>' is changed to a '^' on the
274       action prior to which the old target is renamed to a temporary, and the
275       '-' is changed to a '=' on the action where the temporary is used.
276
277       Under  -n,  none  of  the  actions are performed, but messages like the
278       above are printed on the standard output with the ": done." omitted.
279
280       The output generated by -n can (after editing, if desired) be fed  back
281       to  mmv  on  the standard input (by omitting the from -- to pair on the
282       mmv command line).  To facilitate this, mmv ignores lines on the  stan‐
283       dard input that look like its own error and "done" messages, as well as
284       all lines beginning with white space, and  will  accept  pattern  pairs
285       with  or  without the intervening "->" (or "-^", "=>", or "=^").  Lines
286       with "(*)" after the target pattern have the effect of enabling -d  for
287       the  files  matching this pattern only, so that such deletions are done
288       silently.
289
290       WARNING: This means that unexpected things may happen if files  matched
291       by  the  patterns contain spaces. See http://bugs.debian.org/149873 for
292       details.
293
294       When feeding mmv its own output, one must remember to specify again the
295       task option (if any) originally used to generate it.
296
297       Although  mmv  attempts  to predict all mishaps prior to performing any
298       specified actions, accidents may happen.  For  example,  mmv  does  not
299       check for adequate free space when copying.  Thus, despite all efforts,
300       it is still possible for an action  to  fail  after  some  others  have
301       already  been  done.  To make recovery as easy as possible, mmv reports
302       which actions have already been done and which are  still  to  be  per‐
303       formed  after such a failure occurs.  It then aborts, not attempting to
304       do anything else.  Once the user has cleared up  the  problem,  he  can
305       feed  this report back to mmv on the standard input to have it complete
306       the task.  (The user is queried for a file name to dump this report  if
307       the standard output has not been redirected.)
308

EXIT STATUS

310       Mmv exits with status 1 if it aborts before doing anything, with status
311       2 if it aborts due to failure after completing some of the actions, and
312       with status 0 otherwise.
313

SEE ALSO

315       mv(1), cp(1), ln(1), umask(1)
316

AUTHOR

318       Vladimir Lanin
319       lanin@csd2.nyu.edu
320

BUGS

322       If  the  search pattern is not quoted, the shell expands the wildcards.
323       Mmv then (usually) gives some error message, but can not determine that
324       the lack of quotes is the cause.
325
326       To  avoid  difficulties in semantics and error checking, mmv refuses to
327       move or create directories.
328
329
330
331                          November 20, 2001 (v1.0lfs)                   MMV(1)
Impressum