diff options
| -rw-r--r-- | mmv.1 | 178 |
1 files changed, 178 insertions, 0 deletions
@@ -0,0 +1,178 @@ +.Dd $Mdocdate: August 12 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 +process ID. +.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 |