How to use renamer plugins (renamer v2)

These docs refer to an old version of renamer

Renamer behaviour is defined by chaining together one or more replacement plugins. Input files are processed by each plugin in the chain, in order, with the output of one plugin being passed as input to the next. The default behaviour chains two built-in plugins: "default" and "index". At any point, you can see a description of the default (or custom) replace chain by viewing the CLI usage instructions (renamer --help):

Replace chain

  ↓ Default   Find and replace strings and regular expressions.
  ↓ Index     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: Default

  -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     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: Index

  --index-format    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`.

You create a custom replace chain by setting the --plugin option one or more times. Some plugins can be used in isolation, for example renamer-case. Install the plugin then use it with the --help option.

$ npm install -g renamer-case
$ renamer --plugin 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. It highlights also that the renamer- prefix of plugins can be omitted for brevity.

$ renamer -d --plugin case --case camel *

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

Important: you must specify the --plugin option for each value passed, i.e. --plugin default --plugin index-dir. This form is invalid: --plugin default index-dir.

$ npm install -g renamer-index-dir
$ renamer --plugin default --plugin index-dir --help

The replace chain.

Replace chain

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

An example invocation.

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