Upgraders, please read the release notes. Please share feedback and improvement ideas here.

renamer

Renamer is a command-line utility to help rename files and folders. It is flexible and extensible via plugins.

Disclaimer

Always run this tool with the --dry-run option until you are confident the results look correct.

Synopsis

_The examples below use double quotes to suit Windows users. MacOS & Linux users should use single quotes._

As input, renamer takes a list of filenames or glob patterns plus some options describing how you would like the files to be renamed.

``
$ renamer [options] [file...]
`

This trivial example will replace the text jpeg with jpg in all file and directory names in the current directory.

`
$ renamer --find jpeg --replace jpg *
`

As above but operates on all files and folders recursively.

`
$ renamer --find jpeg --replace jpg "**"
`

$3

If no filenames or patterns are specified, renamer will look for a newline-separated list of filenames on standard input. This approach is useful for crafting a specific input list using tools like find. This example operates on files modified less than 20 minutes ago.

`
$ find . -mtime -20m | renamer --find jpeg --replace jpg
`

Same again but with a hand-rolled input of filenames and glob patterns. Create an input text file, e.g. files.txt:

`
house.jpeg
garden.jpeg
img/*
`

Then pipe it into renamer.

`
$ cat files.txt | renamer --find jpeg --replace jpg
`

$3

Simple example using a regular expression literal. The case-insensitive pattern /one/i matches the input file ONE.jpg, renaming it to two.jpg.

`
$ renamer --find "/one/i" --replace "two" ONE.jpg
`

$3

For more complex renames, or if you just prefer using code, you can write a replace function. Create a module exporting a class which defines a replace method. This trivial example appends the text [DONE] to each file name.

`js
import path from 'path'

class Suffix {
replace (filePath) {
const file = path.parse(filePath)
const newName = file.name + ' [DONE]' + file.ext
return path.join(file.dir, newName)
}
}

export default Suffix
`

Save the above as suffix.js then process all files in the current directory using the above plugin as the replace chain.

`
$ renamer --dry-run --chain suffix.js *

Dry run

✔︎ pic1.jpg → pic1 [DONE].jpg
✔︎ pic2.jpg → pic2 [DONE].jpg

Rename complete: 2 of 6 files renamed.
`

Views

The following gif demonstrates the default view (with and without --verbose mode), the built-in alternative views (long, diff and one-line) and a custom view.

Further reading

Please see the wiki for

* Usage examples.
* More information about using plugins and writing plugins.
* The full list of command-line options.

For more information on Regular Expressions, see this useful guide.

Install

First, ensure Node.js v14 or above is installed.

To install renamer globally as a part of your regular command-line tool kit:

`
$ npm install --global renamer
`

To install renamer as a development dependency of your project:

`
$ npm install --save-dev renamer
``

*

© 2012-24 Lloyd Brookes \<75pound@gmail.com\>.

Tested by test-runner.