How to use replace chain plugins

These docs are for renamer v3. See this page for renamer v2 docs.

Renamer behaviour is defined by chaining together one or more replace chain plugins. Input files are processed by each plugin in the chain, in order, with the output of one plugin being passed to the input of the next. For example, if the first item in the chain adds a prefix and the second adds a suffix then the final output will have both a prefix and suffix.

By default, renamer chains two built-in plugins: find-replace and index-replace. At any point, you can see a description of the loaded replace chain by viewing the CLI usage instructions (renamer --help):

Replace chain

  ↓ FindReplace    Find and replace strings and regular expressions.
  ↓ IndexReplace   Replace the `{{index}}` token in a path with a number incremented for each file renamed.

Further down you will see options specific to the loaded plugins.

Plugin: FindReplace

  -f, --find string           Optional find string (e.g. `one`) or regular expression literal (e.g.
                              `/one/i`). If omitted, the whole filename will be matched and replaced.
  -r, --replace string        The replace string. If omitted, defaults to an empty string.
  -e, --path-element string   The path element to rename, valid values are `base` (the default), `name` and
                              `ext`. For example, in the path `pics/image.jpg`, the base is `image.jpg`,
                              the name is `image` and the ext is `.jpg`.

Plugin: IndexReplace

  --index-format string   The format of the number to replace `{{index}}` with. Specify a standard
                          printf format string, for example `%03d` would yield 001, 002, 003 etc.
                          Defaults to `%d`.
  --index-root string     The initial value for `{{index}}`. Defaults to 1.

You create a custom replace chain by setting the --chain option one or more times. All plugins can be used in isolation or combined with others. For example, install the renamer-case plugin then view its docs with the --help flag.

Note: In this tutorial we install npm modules globally for general use on the command line but you can install them locally too.

$ npm install --global renamer-case
$ renamer --chain renamer-case --help

You'll see the replace chain now consists of this one single plugin.

Replace chain

  ↓ RenamerCase   Renamer plugin to set the case of a filename.

Near the bottom of the usage guide you'll see a list of options it accepts.

Plugin: RenamerCase

  --case    Renames the file using the specified case. Possible values: camel, kebab,
            lower, upper, snake, start.

This example changes the case of all input file names to camel-case.

$ renamer --dry-run --chain renamer-case --case camel lib/*

Dry run

✔︎ lib/cli-app.mjs → lib/cliApp.mjs
✔︎ lib/cli-options.mjs → lib/cliOptions.mjs
✔︎ lib/rename-file.mjs → lib/renameFile.mjs
✔︎ lib/replace-chain.mjs → lib/replaceChain.mjs

Rename complete: 4 of 7 files renamed.

Some plugins work best following the built-in find-replace plugin, for example renamer-index-dir. This plugin works the same as the built-in index-replace except each directory has its own count.

Important: you must specify the --chain option for each value passed, i.e. --chain find-replace --chain renamer-index-dir. This form is invalid: --chain find-replace renamer-index-dir.

$ npm install --global renamer-index-dir
$ renamer --chain find-replace --chain renamer-index-dir --help

The replace chain.

Replace chain

  ↓ FindReplace       Find and replace strings and regular expressions.
  ↓ RenamerIndexDir   Replaces the `{{index}}` token, resetting the counter for each folder visited.

An example invocation.

$ renamer --chain find-replace --chain renamer-index-dir --find "/$/" --replace {{index}} "*/*"