.Dd $Mdocdate: August 15 2023 $
.Dt MMV 1
.Os
.Sh NAME
.Nm mmv
.Nd mapped file moves
.Sh SYNOPSIS
.Nm
.Op Fl 0deinv
.Ar command
.Op Ar argument ...
.Sh DESCRIPTION
The
.Nm
utility is a tool for moving- and renaming files by mapping filenames using a
provided
.Ar command
and
.Ar argument Ns s.
When invoked, the program specified by
.Ar command
with the arguments
.Ar argument ...
is invoked to read filenames from the standard input and output new filenames to
the standard output.
.Nm
will then move all files that were provided via the standard input to their
coressponding destinations which
.Ar command
printed to the standard output.
In other words,
.Ql mmv cat
can be seen as a no\-op.
You can find a variety of examples under the
.Sx EXAMPLES
section.
.Pp
It is also very important to remember that filenames may contain newline
characters.  The
.Fl 0 ,
.Fl e ,
and
.Fl i
options might be of use to help you properly handle these.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl 0 , Fl Fl nul
Treat filenames read from the standard input as being nul\-byte
.Pq Sq \e0
separated instead of newline
.Pq Sq \en
separated.
This is useful if input filenames might contain embedded newline characters.
.It Fl d , Fl Fl dry-run
Print the renamings that would take place with the given inputs and arguments to
the standard error without actually executing any moves.  It is recommended you
run
.Nm
with this flag before performing any changes to ensure nothing unexpected occurs.
.It Fl e , Fl Fl encode
Encode newlines in filenames as the literal string
.Sq \en
and backslashes as the literal string
.Sq \e\e .
This will allow you to treat multi\-line filenames as single\-line ones.
An example usecase of this is detailed in the
.Sx EXAMPLES
section.
.It Fl i , Fl Fl individual
Spawn a new instance of the command provided to
.Nm
for each input filename.
This is useful for use in conjunction with the
.Fl 0
option when provided mapping command doesn’t have built\-in support for
nul\-byte delimited input.
.It Fl n , Fl Fl no-backup
The default behavior of
.Nm
is to create a backup of your input files in
.Pa $XDG_CACHE_DIR/mmv
to avoid dataloss in the case of an error.
If for whatever reason you do not want to create this directory
.Pq perhaps for performance reasons
then you can use this option.
.It Fl v , Fl Fl verbose
Display output to the standard error detailing which files and directories are
being created, moved, and removed.
.El
.Sh FILES
.Bl -tag -width $XDG_CACHE_DIR/mmv
.It Pa $XDG_CACHE_DIR/mmv
The backup directory where a copy of your input files are stored during
operation.  Input files are backed up in a subdirectory whose name is the
timestamp of when the directory was created.
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
Swap the files
.Pa foo
and
.Pa bar :
.Pp
.Dl $ ls foo bar | mmv tac
.Pp
Rename all files in the current directory to use hyphens
.Pq Sq \-
instead of spaces:
.Pp
.Dl $ ls | mmv tr ' ' '-'
.Pp
Rename all *.jpeg files to use the
.Sq .jpg
file extension:
.Pp
.Dl $ ls *.jpeg | mmv sed 's/\e.jpeg$/.jpg/'
.Pp
Rename a given list of movies to use lowercase letters and hyphens instead of
uppercase letters and spaces, and number them so that they’re properly ordered
in globs
.Po
e.g. rename
.Pa The Return of the King.mp4
to
.Pa 02-the-return-of-the-king.mp4
.Pc :
.Pp
.Bd -literal -offset indent
$ ls 'The Fellowship of the Ring.mp4' ... 'The Two Towers.mp4' | \e
	mmv awk '{ gsub(" ", "-"); printf "%02d-%s", NR, tolower($0) }'
.Ed
.Pp
Rename files interactively in your editor while encoding newlines into the
literal string
.Sq \en ,
making use of
.Xr vipe 1
from moreutils:
.Pp
.Dl $ ls | mmv -0e vipe
.Pp
Rename all C source code and header files in a git repository to use snake_case
instead of camelCase using the GNU
.Xr sed 1
.Ql \eL
extension:
.Pp
.Dl $ git ls-files '*.[ch]' | mmv sed 's/[A-Z]/\eL_&/g'
.Pp
Lowercase all filenames within a directory hierarchy which may contain newline
characters:
.Pp
.Dl $ find . -print0 | mmv -0 tr A-Z a-z
.Pp
Map filenames which may contain newlines in the current directory with the
command
.Ql cmd ,
which itself does not support nul\-byte separated entries.
This only works assuming your mapping doesn’t require any context outside of the
given input filename
.Po
for example, you would not be able to number your files as this requires
knowledge of the input files position in the input list
.Pc :
.Pp
.Dl $ ls --zero | mmv -0i cmd
.Sh SEE ALSO
.Xr awk 1 ,
.Xr cp 1 ,
.Xr mv 1 ,
.Xr sed 1 ,
.Xr vipe 1
.Pp
.Lk https://thomasvoss.com/prj/mmv "Extended Description and -Documentation"
.Sh AUTHORS
.An Thomas Voss Aq Mt mail@thomasvoss.com