MMV(1) Manual Page

  • Home
  • Back

  • MMV(1) General Commands Manual MMV(1)

    mmv, mcpmapped file moves and -copies

    mmv [-0bdeinv] command [argument ...]

    mcp [-0bdeiv] command [argument ...]

    The mmv and mcp utilities are tools for copying-, moving-, and renaming files by mapping filenames using a provided command and arguments. When invoked, the program specified by command with the arguments argument ... is invoked to read filenames from the standard input and output new filenames to the standard output. mmv will then move all files — and mcp will then copy all files — that were provided via the standard input to their coressponding destinations which command printed to the standard output. In other words, ‘mmv cat’ can be seen as a no-op. You can find a variety of examples under the EXAMPLES section.

    It is also very important to remember that filenames may contain newline characters. The -0, -e, and -i options might be of use to help you properly handle these.

    The options are as follows:

    , --nul
    Treat filenames read from the standard input as being nul-byte (‘\0’) separated instead of newline (‘\n’) separated. This is useful if input filenames might contain embedded newline characters.
    , --basename
    Only apply the mapping command to the basenames of the given file paths. This stops you from accidentally mutating directory components, which is not typically a desired behavior. If no basename can be derived (the root directory for example has no basename), then a warning diagnostic will be printed to the standard error, and the path will remain unchanged.
    , --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 mmv and mcp with this flag before performing any changes to ensure nothing unexpected occurs.
    , --encode
    Encode newlines in filenames as the literal string ‘\n’ and backslashes as the literal string ‘\\’. This will allow you to treat multi-line filenames as single-line ones. An example usecase of this is detailed in the EXAMPLES section.
    , --individual
    Spawn a new instance of the command provided to mmv or mcp for each input filename. This is useful for use in conjunction with the -0 option when provided mapping command doesn’t have built-in support for nul-byte delimited input.
    , --no-backup
    The default behavior of mmv is to create a backup of your input files in $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 (perhaps for performance reasons) then you can use this option.

    This flag does not apply to mcp.

    , --verbose
    Display output to the standard error detailing which files and directories are being created, moved, and removed.

    $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. If the XDG_CACHE_DIR environment variable is not set, mmv will default to using $HOME/.cache/mmv.

    The mmv and mcp utilities exit 0 on success, and >0 if an error occurs.

    Swap the files foo and bar:

    $ ls foo bar | mmv tac

    Rename all files in the current directory to use hyphens (‘-’) instead of spaces:

    $ ls | mmv tr ' ' '-'

    Rename all *.jpeg files to use the ‘.jpg’ file extension:

    $ ls *.jpeg | mmv sed 's/\.jpeg$/.jpg/'

    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 (e.g. rename The Return of the King.mp4 to 02-the-return-of-the-king.mp4):

    $ ls 'The Fellowship of the Ring.mp4' ... 'The Two Towers.mp4' | \
    	mmv awk '{ gsub(" ", "-"); printf "%02d-%s", NR, tolower($0) }'

    Rename files interactively in your editor while encoding newlines into the literal string ‘\n’, making use of vipe(1) from moreutils:

    $ ls | mmv -0e vipe

    Rename all C source code and header files in a git repository to use snake_case instead of camelCase using the GNU sed(1)\L’ extension:

    $ git ls-files '*.[ch]' | mmv sed 's/[A-Z]/\L_&/g'

    Lowercase all filenames within a directory hierarchy which may contain newline characters:

    $ find. -print0 | mmv -0 tr A-Z a-z

    Map filenames which may contain newlines in the current directory with the command ‘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 (for example, you would not be able to number your files as this requires knowledge of the input files position in the input list):

    $ ls --zero | mmv -0i cmd

    Uppercase the files in the /foo/bar directory, while leaving the names of foo and bar unchanged:

    $ ls /foo/bar/* | mmv -b tr a-z A-Z

    awk(1), cp(1), mv(1), sed(1), vipe(1)

    Extended Description and -Documentation

    Thomas Voss <[email protected]>

    September 24, 2023 MangoOS