NAME

mved - carefully rename multiple files and directories

SYNOPSIS

 usage: mved [options] src dst
 options:

   --help    - Print the help message then exit
   --version - Print the version message then exit
   -h        - Print the help message then exit
   -m        - Print the manpage then exit
   -w        - Print the manpage in HTML format then exit
   -r        - Print the manpage in nroff format then exit
   -n        - Don't rename anything. Just print commands
   -f        - Force dangerous actions (Check with -n first!)
   -q        - Don't print skipping or removing messages
   -v        - Print the equivalent mv commands (implied by -d)
   -d        - Print debug messages
   -b #      - Set the number of backslashes to check for (default 16)

DESCRIPTION

mved carefully renames multiple files and directories. The src argument is like a shell filename glob pattern that specifies the set of files or directories to rename. The dst argument is a pattern that specifies the new names for the set of files or directories. The src argument can contain most of the basic shell filename glob constructs (i.e. "?", "*", "[...]" and "{...,...}") as well as "=" which is a synonym for "*". If any normal shell filename glob constructs are used, they will need to be quoted to prevent the shell from performing filename glob expansion. This is not necessary when the only construct used is "=". However, the "=" character can be special in some shells and so might need to be quoted as well. Note that "[^...]" complement character classes and complex uses of "{...,...}" multiple patterns are not supported.

There are two styles of dst argument. In the implicit style, "=" represents the text that matches the (positionally) corresponding glob construct in the src argument. In the explicit style, "=#=" (where # is an integer from 1 to 9) represents the text that matches the #-th glob construct in the src argument. The two styles cannot be mixed.

mved renames files or directories one at a time. If the -v verbose option is supplied, the equivalent mv commands are printed. If one of the renaming operations fails, any that did succeed are undone and the operation is aborted.

Before renaming any files or directories, mved checks for any potentially dubious consequences. If a source path is equal to its corresponding destination path, that (redundant) renaming operation is skipped. The user is informed unless the -q quiet option is supplied. If a source path is equal to any other destination path, mved gets nervous and exits unless the -f force option is supplied. If the same path is the destination for multiple source paths, mved exits unless the -f force option is supplied. If any file or directory path to be created already exists, mved exits unless the -f force option is supplied. If forced, mved will first remove any existing destination files or directories. The user will be informed unless the -q quiet option is supplied. If mved fails to remove an existing destination file or directory, it will exit immediately.

OPTIONS

--help

Print the help message then exit.

--version

Print the version message then exit.

-h

Print the help message then exit.

-m

Print the manpage then exit. This is equivalent to executing man mved but this works even when the manpage isn't installed.

-w

Print the manpage in HTML format then exit. This lets you install the manpage in HTML format with commands like:

  mkdir -p /usr/local/share/doc/mved/html &&
  mved -w > /usr/local/share/doc/mved/html/mved.1.html

-r

Print the manpage in nroff format then exit. This lets you install the manpage with a command like:

  mved -r > /usr/local/share/man/man1/mved.1

-n

Don't rename anything. Just print the equivalent mv commands (and possibly rm commands) then exit.

-f

Force mved to obey even when it looks like a mistake. If you force mved to rename a file or directory to an existing file or directory, the existing file or directory will be removed first. Never use this without using the -n option first to see what you are telling mved to do, and verifying that it is what you really, really want to do.

-q

Don't print "Skipping" messages when a source path matches its corresponding destination path. Don't print "Removing" messages when forced to remove existing files or directories.

-v

Print the equivalent mv commands when renaming each file or directory. This is implied by the -d option.

-d

Print debug messages that show the src and dst arguments before and after translation from shell filename glob patterns to regular expressions. Also print the equivalent mv commands when renaming each file or directory.

-b #

Specify how many preceding backslashes to check for when determining whether or not special characters are escaped. The default is 16 which should be more than enough (unless there are files or directories with many many consecutive backslashes in their names). If it is too low, mved will not work properly for names containing lots of backslashes. So don't do that.

EXAMPLES

  mved =.c~ bak/=.c.bak

    mv a.c~ bak/a.c.bak
    mv b.c~ bak/b.c.bak
    mv c.c~ bak/c.c.bak

  mved '*.[ch]' save-=.=

    mv a.c save-a.c
    mv a.h save-a.h
    mv b.c save-b.c
    mv b.h save-b.h

  mved save-=.= =.=

    mv save-a.c a.c
    mv save-a.o a.o
    mv save-b.c b.c
    mv save-b.o b.o

  mved note= note=.txt

    mv note1 note1.txt
    mv note2 note2.txt
    mv note3 note3.txt

  mved '[0-9][0-9][0-9][0-9][0-9][0-9]*' 19=5==6=-=3==4=-=1==2==7=

    mv 191299-app.log 1999-12-19-app.log
    mv 211299-app.log 1999-12-21-app.log
    mv 251299-app.log 1999-12-25-app.log
    mv 281299-app.log 1999-12-28-app.log

  mved '{abc,def}.*' =-v2.=

    mv abc.txt abc-v2.txt
    mv def.txt def-v2.txt

Note: Files and directories whose names start with a dot (".") are not matched by src arguments that start with "?" or "*" or even "[.]". The leading dot must be matched explicitly. This is like normal shell behaviour.

EXIT STATUS

mved's exit status is zero upon success, or non-zero upon failure. Upon failure, effectively no files or directories will have been renamed, but some may have been renamed and then renamed back to their original names. In some very peculiar and unlikely circumstances, it's conceivable that renaming files or directories (that have been renamed) back to their original names might fail. If that ever happens, error messages will tell you which renaming attempts failed so that you can recover manually.

BUGS

Files and directories are only renamed, not copied, so it's impossible to mved files from one file system to another. Use mv for this. Then rename them with mved. This is not really a bug. It's just a limitation. And it's a safety feature: mved is only for renaming multiple files and directories; mv is good for moving data.

If a destination path contains a parent directory that does not already exist, mved will not automatically create it. Use mkdir first if you need this to happen.

The src argument doesn't support the "[^...]" complement character class glob pattern which is supported by most shells nowadays. The library used for globbing is based on csh which is unfortunate.

The src argument only has very limited support for the "{...,...}" filename-generating multiple glob pattern. They can't be nested and they can't contain any other filename glob patterns or backslash-escaped characters either. So things like "{a,{1,2,3},b}" and "{a*,b?}" and "{a\*,b\?}" won't work.

Even though mved is thoroughly tested and has been in use for decades, there are, presumably, as yet unknown bugs and they might even lose files. My advice is to always use the -n option first, never use the -f option, and always keep backups of anything precious.

LICENSE

mved is released under the terms of the GPLv2+ https://www.gnu.org/licenses/.

HISTORY

Many years ago on a MIPS far away, there was a program called mved that renamed multiple files using =. It was very useful but I haven't seen it since.

SEE ALSO

mv(1), rename(2), rm(1), unlink(2), mkdir(1), rmdir(2), cp(1), scp(1), rsync(1).

AUTHOR

20200625 raf <raf@raf.org>

URL

http://raf.org/mved/, https://github.com/raforg/mved/