dmulholl / vimv

A command line utility for batch-renaming files.

Vimv

This simple 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

If you don't have a Rust compiler available, you can easily install one by following the instructions here. You don't need any knowledge of Rust to build, install, or use vimv.

AUR

If you are using Arch Linux, you can get vimv from the AUR:

yay -S vimv

Or

paru -S vimv

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 renamed paths will be created
  as required.

  If the input file list is empty, Vimv defaults to listing the
  contents of the current working directory.

  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 or directory by prefixing its name with a
  '#' symbol. Deleted files and directories are moved to the system's
  trash/recycle bin.

Arguments:
  [files]                   List of files to rename.

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

Flags:
  -f, --force               Overwrite existing files.
  -h, --help                Print this help text.
  -q, --quiet               Quiet mode -- only report errors.
  -s, --stdin               Read the list of input files from stdin.
  -v, --version             Print the version number.

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 or directory by prefixing its name with a # symbol. Deleted files and directories are moved to the system's trash/recycle bin.

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 --stdin

Note that your editor may not appreciate inheriting a standard input stream that's connected to a pipe rather than a terminal. Graphical editors tend to handle this situation without complaint, as does Neovim in the terminal. Vim prints a warning, then works, then borks your terminal session until you run reset. YMMV.

(Because of this inconsistent behaviour, this feature is hidden behind a --stdin/-s flag.)

License

Zero-Clause BSD (0BSD).

vimv's Issues

Support to use git mv as an option?

Using git mv and git mv --dry-run if specified?

Add support for cycle renaming

I realize, this feature might complicate the implementation, but you also might find it interesting.

1. Open two files: vimv a b.
2. Exchange the file's names, so a becomes b and b becomes a.
3. Save and exit.
   What happens: Error: the output file 'b' already exists, use --force to overwrite.
   Suggestion: actually, rename the files.

I know, this renamer (written in Go) supports it.

Support alternate sorting option

First of all, thanks for this program. It's very useful to me. Are you open to adding filename sorting instead of the default vector sort? I use nnn (the terminal file viewer) all the time and I'm often renaming files with one tmux pane while another tmux pane has nnn open to look through directory contents. The current sorting is way different from nnn which makes this process difficult. I've forked the repo and changed the sorting to match almost perfectly. I was thinking it could be cool to have a --sort <algo_name> flag with options default and nnn to start with? Is that outside the scope of the project?

Here's my commit that changed the sorting for reference.

vimv cannot handle files containing certain unicode characters

I have the following file: 　-SsV0tZMUCNE.webm (unicode representation is \343\200\200-SsV0tZMUCNE.webm) which vimv cannot open.

I get the following error:

vimv "　-SsV0tZMUCNE.webm"
Error: the input file '-SsV0tZMUCNE.webm' does not exist.

Make no argument invokation useful

Currently, if no commandline arguments are passed the program quits. It would be better if invoking with no arguments cause the program to open the editor with all the files/folder in the current directory to rename.
This was my thought process when I installed the program for the first time. I was confused when the program exited when tried running the program with no args. Had to look at the source code to figure out that it exits if no args are provided

My current workaround for this is to add a shell alias like this

alias br="vimv *"

I mean i understand it's a small change.. but hey, it's two less keys pressed

Show errors in vim it self

on save perhaps, when the temp file is saved show the stdout of a dry run inside of vim

installation option using homebrew

I wanted to use this program along with lf but couldn't find an option to install this using homebrew. Could there be an option to do that

Directories break cycles support

Steps to reproduce:

mkdir a b
vimv a b

Swapping the two lines and saving yield the following error message:Error: cannot overwrite the existing directory 'b'.

I'm running vimv 1.7.3.