Rename-cli NPM

Rename-CLI

A cross-platform tool for renaming files quickly, especially multiple files at once.

Note Version 7 has big changes from version 6, if you are staying on version 6 you can find the old documentation here

gif preview

Installation

npm: npm i -g rename-cli@beta (sudo if necessary)

Features

Variable replacement and filtering of new file name (powered by Nunjucks)
Glob file matching
Undo previous rename
Customize by adding your own variables and filters
Auto-indexing when renaming multiple files to the same name
RegEx match/replace
Exif data support

Usage

rename [options] file(s) new-file-name

Or simply type rename for an interactive cli with live previews of rename operations.

Note: Windows users (or anyone who wants to type one less letter) can use rname instead of rename since the rename command already exists in Windows

The new file name does not need to contain a file extension. If you do not specifiy a file extension the original file extension will be preserved.

Note: if you include periods in your new file name, you should include a file extension to prevent whatever is after the last period from becoming the new extension. I recommend using .{{ext}} to preserve the original file etension.

Options

-h, --help: Show help
-i, --info: View online help
-w, --wizard: Run a wizard to guide you through renaming files
-u, --undo: Undo previous rename operation
-k, --keep: Keep both files when new file name already exists (append a number)
-f, --force: Force overwrite without prompt when new file name already exists and create any missing directories
-s, --sim: Simulate rename and just print new file names
-n, --noindex: Do not append an index when renaming multiple files
-d, --ignoredirectories: Do not rename directories
--sort: Sort files before renaming. Parameter: alphabet (default), date-create (most recent first), date-modified (most recent first), size (biggest first). Include the word reverse before or after (use a dash or no space) to reverse the sort order. -p, --prompt: Print all rename operations to be completed and confirm before proceeding
--notrim: Do not trim whitespace at beginning or end of ouput file name
--nomove: Do not move files if their new file name points to a different directory
--noext: Do not automatically append a file extension if one isn't supplied (may be necessary if using a variable for an extension)
--createdirs: Automatically create missing directories (cannot be used with --nomove)
--printdata: Print the data available for a file

Built-in Variables

{{i}} Index: The index of the file when renaming multiple files to the same name. If you do no include {{i}} in your new file name, the index will be appended to the end. Use the --noindex option to prevent auto-indexing.

{{f}} File name: The original name of the file.

{{p}} Parent directory: The name of the parent directory.

{{isDirectory}} Is directory: true/false. Useful for conditionally adding a file extension to files and not directories with {% if isDirectory %}...

{{os.x}} Operating System: Information about the OS/user. Replace x with homedir, hostname, platform, or user

{{date.x}} Dates: Insert a date. Replace x with current (the current date/time), create (the file's created date/time), access (the file's last accessed date/time) or modify (the file's last modified date/time)

{{g}} GUID: A pseudo-random globally unique identifier.

{{exif.x}} Exif: Photo Exif Information. Replace x with iso, fnum, exposure, date, width, or height

You can also add your own variables. See the Customize section for more info.

Filters

String case manipulation

lower - all lowercase
upper - ALL UPPERCASE
camel - something like-this → somethingLikeThis
pascal - something like-this → SomethingLikeThis

replace('something', 'replacement') - replace a character or string with something else.

rename "bills file.pdf" "{{ f | replace('bill', 'mary') | pascal }}"

bills file.pdf → MarysFile.pdf

date - format a date to a specific format, the default is YYYYMMDD if no parameter is passed. To use your own format, simply pass the format as a string parameter to the date filter. Formatting options can be found here.

rename *.txt "{{ d.now | date }}-{{f}}"

a.txt → 20200502-a.txt
b.txt → 20200502-b.txt
c.txt → 20200502-c.txt

rename *.txt "{{ d.now | date('MM-DD-YYYY') }}-{{f}}"

a.txt → 05-02-2020-a.txt
b.txt → 05-02-2020-b.txt
c.txt → 05-02-2020-c.txt

match(RegExp[, flags, group num/name]) - match substring(s) using a regular expression. The only required parameter is the regular expression (as a string), it also allows for an optional parameter flags (a string containing any or all of the flags: g, i, m, s, u, and y, more info here), and an optional parameter of the group number or name. Named groups cannot be used with the global flag.

rename *ExpenseReport* "archive/{{ f | match('^.+(?=Expense)') }}/ExpenseReport.docx" --createdirs

JanuaryExpenseReport.docx → archive/January/ExpenseReport.docx
MarchExpenseReport.docx → archive/March/ExpenseReport.docx

regexReplace(RegExp[, flags, replacement]) - replace the first regex match with the replacement string. To replace all regex matches, pass the g flag. flags and replacement are optional, the default value for replacement is an empty string.

rename test/* "{{ f | regexReplace('(^|e)e', 'g', 'E') }}"

test/eight.txt → Eight.txt
test/eighteen.txt → EightEn.txt
test/eleven.txt → Eleven.txt

Customize

Variables

The first time you run the rename command a file will be created at ~/.rename/userData.js, this file can be edited to add new variables that you can access with {{variableName}} in your new file name. You can also override the built-in variables by naming your variable the same. The userData.js file contains some examples.

// These are some helpful libraries already included in rename-cli
// All the built-in nodejs libraries are also available
// const exif = require('jpeg-exif'); // https://github.com/zhso/jpeg-exif
// const fs = require('fs-extra'); // https://github.com/jprichardson/node-fs-extra
// const n2f = require('num2fraction'); // https://github.com/yisibl/num2fraction
// const moment = require('moment'); // https://momentjs.com/

module.exports = function(fileObj, descriptions) {
  let returnData = {};
  let returnDescriptions = {};

  // Put your code here to add properties to returnData
  // this data will then be available in your output file name
  // for example: returnData.myName = 'Your Name Here';
  // or: returnData.backupDir = 'D:/backup';

  // Optionally, you can describe a variable and have it show when printing help information
  // add the same path as a variable to the returnDescriptions object with a string description
  // for example: returnDescriptions.myName = 'My full name';
  // or: returnDescriptions.backupDir = 'The path to my backup directory';

  if (!descriptions) return returnData;
  else return returnDescriptions;
};

The fileObj that is passed to the function will look something like this:

{
  root: '/',
  dir: '/Users/myusername/Projects/node-rename-cli/test',
  base: 'somefile.txt',
  ext: '.txt',
  name: 'somefile',
  isDirectory: false,
  newName: 'the-new-name-of-the-file',
  newNameExt: '.txt',
  options: {
    regex: false,
    keep: false,
    force: false,
    simulate: true,
    prompt: false,
    verbose: false,
    noIndex: false,
    noTrim: false,
    ignoreDirectories: false,
    noMove: false,
    createDirs: false,
    noExt: false,
    noUndo: false,
    sort: false
  },
  size: 21,
  dateCreate: 1588887960364.1008,
  dateModify: 1588887960364.2664
}

Filters

The first time you run the rename command a file will be created at ~/.rename/userFilters.js, this file can be edited to add new filters that you can access with {{someVariable | myNewFilter}} in your new file name.

One place custom filters can be really handy is if you have files that you often receive in some weird format and you then convert them to your own desired format. Instead of writing some long, complex new file name, just write your own filter and make the new file name {{f|myCustomFilterName}}. You can harness the power of code to do really complex things without having to write a complex command.

Each filter should accept a parameter that contains the value of the variable passed to the filter (str in the example below). You can optionally include more of your own parameters as well. The function should also return a string that will then be inserted into the new file name (or passed to another filter if they are chained). The userFilters.js file contains some examples.

// Uncomment the next line to create an alias for any of the default Nunjucks filters https://mozilla.github.io/nunjucks/templating.html#builtin-filters
// const defaultFilters = require('../nunjucks/src/filters');
// These are some helpful libraries already included in rename-cli
// All the built-in nodejs libraries are also available
// const exif = require('jpeg-exif'); // https://github.com/zhso/jpeg-exif
// const fs = require('fs-extra'); // https://github.com/jprichardson/node-fs-extra
// const n2f = require('num2fraction'); // https://github.com/yisibl/num2fraction
// const moment = require('moment'); // https://momentjs.com/

module.exports = {
  // Create an alias for a built-in filter
  // big: defaultFilters.upper,
  // Create your own filter
  // match: function(str, regexp, flags) {
  //   if (regexp instanceof RegExp === false) {
  //     regexp = new RegExp(regexp, flags);
  //   }
  //   return str.match(regexp);
  // }
};