Add a manual page

1 files changed, 178 insertions, 0 deletions

diff --git a/mmv.1 b/mmv.1
new file mode 100644
index 0000000..0316517
--- /dev/null
+++ b/mmv.1
@@ -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