Vimv

A command line utility for batch-renaming files.


This command line utility lets you batch-rename files from the comfort of your favourite text editor. You specify the files to be renamed as arguments, e.g.

$ vimv *.mp3

The list of files will be opened in the editor specified by the $EDITOR environment variable, one filename per line. Edit the list, save, and exit. The files will be renamed to the edited filenames.

Installation

Vimv is written in Rust — if you have a Rust compiler available you can install it directly from the package index using cargo:

$ cargo install vimv

You can find the source files on Github and the package on crates.io.

Interface

Run vimv --help to view the command line help:

Usage: vimv [files]

  This utility lets you batch rename files using a text editor.
  Files to be renamed should be supplied as a list of command-line
  arguments, e.g.

    $ vimv *.mp3

  The list of files will be opened in the editor specified by the
  $EDITOR environment variable, one filename per line. Edit the
  list, save, and exit. The files will be renamed to the edited
  filenames. Directories along the path will be created as required.

  Vimv supports cycle-renaming. You can safely rename A to B, B to
  C, and C to A in a single operation.

  Use the --force flag to overwrite existing files that aren't part
  of a renaming cycle. (Existing directories are never overwritten.
  If you attempt to overwrite a directory the program will exit with
  an error message and a non-zero status code.)

  You can delete a file by 'renaming' it to a blank line, but only
  if the --delete flag has been specified. Deleted files are
  moved to the system's trash/recycle bin.

  If the --git flag is specified then git will be used to rename or
  delete any files which are being tracked by git. (Note that this
  bypasses the recycle bin for deleted files.)

Arguments:
  [files]                   List of files to rename.

Options:
  -e, --editor <name>       Specify the editor to use.

Flags:
  -d, --delete              Enable file deletion.
  -f, --force               Overwrite existing files.
  -g, --git                 Use git for git-tracked files.
  -h, --help                Print this help text.
  -q, --quiet               Only report errors.
  -v, --version             Print the version number.

Quick Tip

Vimv simply ignores any filenames that haven't been changed so you don't have to be overly fussy about specifying its input. You can run:

$ vimv *

to get a full listing of a directory's contents, change just the items you want, and Vimv will ignore the rest.

Cycle Renaming

Vimv supports cycle-renaming. You can safely rename A to B, B to C, and C to A in a single operation.

Deleting Files

You can delete a file by 'renaming' it to a blank line, but only if the --delete flag has been specified. Deleted files are moved to the system's trash/recycle bin.

Git Support

If you specify the --git flag Vimv will use git mv to rename files which are being tracked by git and git rm to delete files which are being tracked by git. Note that this bypasses the recycle bin for deleted files.

Graphical Editors

If you want to use a graphical editor like VS Code or Sublime Text instead of a terminal editor like Vim then (depending on your operating system) you may need to add a 'wait' flag to the $EDITOR variable to force the editor to block, e.g.

EDITOR="code -w"      # for VS Code
EDITOR="subl -w"      # for Sublime Text
EDITOR="atom -w"      # for Atom

The same flag can be used with the --editor option, e.g.

$ vimv *.mp3 --editor "code -w"

Piped Input

You can pipe a list of filenames into Vimv from a tool like ls or fd, e.g.

$ fd .txt | vimv

Note that your editor may not appreciate inheriting a stdin that's connected to a pipe rather than a terminal. In my experience, all graphical editors work fine, as does Neovim in the terminal. Vim prints a warning, then works, then borks your terminal session until you run reset. YMMV.

License

Vimv is released under an MIT license.