rnm

Section: Utility (1)
Updated: Thu Oct 15 2015

NAME

rnm - Bulk rename utility
 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
TERMINOLOGY
EXAMPLES
LOGDIR
EXITSTATUS
BUGREPORT
AUTHOR
WEB

SYNOPSIS

rnm [-ns name-string ] file-path ...

One of the options of -ns or -nsf or -rs is mandatory. Options are **not** sequential, their position in the argument list have no significance. For example: rnm filepath -ns name is the same as rnm -ns name filepath. Though passing the directory/file path at the end of the argument list is considered to be safe and wise.

Options are case insensitive, i.e -ssF and -ssf are the same.  

DESCRIPTION

Bulk Rename Utility written in C++. Files and directories can be passed as command line arguments to rename them in bulk according to some naming scheme ( Name String ). If no file or directory path is passed as command line argument, it will wait for user to type the path i.e it will take the path from standard input (>=version 3.0.1). It uses ECMAScript regex as the default regex to provide search (and replace) functionality, other regex modes ( POSIX compliant basic and extended regex) are available through ( -re ) option. It provides an undo functionality ( rnm -u )too to move back an unwanted rename operation. You can also run a simulation instead of actual rename to view the potential outcome as program output on terminal with the -sim option.  

OPTIONS

-h, --help
Show help menu.
--index,--start-index, -i,
-si value : Starting index.
--end-index,
-ei value : End index i.e index to stop renaming from. It is only for files inside a directory that is being recursively taken due to a depth value greater than 0, i.e it works on directory index. Note that directory index /id/ will renew in each directory i.e in each directory rename will be performed from start index to end index.

--increment-value,
-inc value : Increment value (floating point decimal). The amount, index will be incremented or decremented in each iteration. Decremented index is available through name string rule: /-i/ , /-id/ etc..

--line-increment-value,
-linc value : The amount line count will be incremented or decremented in each iteration. This is always a positive integer.
--index-field-length,
-ifl value : Index field length. Non occupied field will be filled with index field fillers (set with -iff ). iff is set to the character 0 by default.

--index-field-filler,
-iff single-character : Not occupied field in index will be filled with a character which is set by this option.

--index-field-precision,
-ifp value : Index is a floating point decimal value. This sets the precision i.e the number of digits that should be taken after the decimal point.

--name-string,
-ns string : Name string.

--name-string-file,
-nsf , -ns/f file-path : Name string file. File containing name string (one per line). -nsf is deprecated (will be removed in future), use -ns/f instead. -ns/f /hist/ i.e a value /hist/ passed as Name string file, will try to take the file from history.

--name-string-file-null-terminated,
-nsfn , -ns/fn file-path : Name String file. This takes a null terminated Name String file, i.e filenames are terminated by null character (\0) instead of new line (\n). -nsfn is deprecated, use -ns/fn instead.

--line, --start-line, -l,
-sl : Start Line number in name string file.
--line-reverse, --start-line-reverse, -lv,
-slv value : Same as -l or -sl , except line number will be decremented in each iteration.

--end-line,
-el value : End line number. Line number to stop renaming from.
--end-line-reverse,
-elv value : Same as -el , except line number will be decremented in each iteration.
--search-string,
-ss string : Search string. String that will be used to search for files with matching names. This is generally a regex if not passed with -ssf option.
--search-string-file,
-ss/f file_path : Search string file. A file containing search string per line.
--search-string-fixed,
-ssf string : Fixed search string (not treated as regex).
--search-string-fixed-file,
-ssf/f file_path : Search string file. Contains fixed search string per line.
--replace-string,
-rs string : Replace string. A string in the form /search_string/replace_string/modifier , see Replace String in TERMINOLOGY section for details.
--replace-string-file,
-rs/f file_path : Replace string file. A file containing replace string per line.
--regex,
-re regex-mode : Regex mode. Available regex modes are POSIX compliant basic & extended regex, regex used by grep , awk , egrep and the default regex is ECMAScript regex.For example, to have a grep like regex, pass the option -re grep , to use POSIX compliant extended regex, pass -re extended

--regex-locale, -rel
If this is passed as argument, regex will follow Locale. that is regex like [a-z] will have their meaning according to the system locale.

--depth,
-dp value : Depth of folder. -1(any negative number) means unlimited depth i.e all files and subdirectories will be included. Other values may be 0 1 2 3 etc... Default depth is 0, i.e directory contents will be ignored.

--file-only, -fo
File only mode. Only files are renamed (not directory). Goes to subdirectory/s if depth ( -dp ) is set to 1 or greater. Default depth is set to 0.

--directory-only, -do
Apply rename on directory only. No subdirectories.

--exclude-directory, -ed
Apply rename on files only, exclude any and all directory and their contents. Forces file only mode regardless of depth ( -dp ) value.
--count-directory, -cd
Count directory in reserved index regardless of other options. Reserves indices for directories even if it is File Only mode.
--count-file, -cf
Count file in reserved index regardless of other options. Reserves indices for files even if it is Directory Only mode.
--sort, -s
Sort files or directories in a natural (human perceivable natural sort) manner.
--sort/g, -s/g
Sort files or directories in general manner (alphabetic sort).
--sort/none, -s/none
Force not to sort anything. Files or directories may or may not be at random order.
--yes, -y
Confirm Yes to all.
--undo, -u
Undo renaming
--version, -v
Version info.
--quiet, -q
Quiet operation.

--force, -f
Apply force. Enables renaming some non permitted files/directories.

--
If this option is passed, anything and everything after it will be taken as file path. Put all options before passing this option.

--show-options, -shop
This shows an info about the various options passed as arguments and how they are being treated behind the scene.

--simulation, -sim
This runs a simulation of rename instead of actual rename operation, and prints all kinds of available outputs. -q option won't have any effect if this option is passed.
 

TERMINOLOGY

Reserved Index
Index will be incremented even if any file is skipped renaming in order to reserve the index for that skipped file

Reverse Index

Decrementing index.

Name String

A string, that is parsed to create names for new files. It can be fixed name which then can be modified for different files at runtime. Name sting is parsed by the following rules (must be wrapped around with filepath delimiter /):

/n/ in name string will be replaced with filename without extension. If used with -nsf option, the filename will be the name taken from the Name String File.

/fn/ in name string will be replaced with full name of the files. If used with -nsf option, full name will be the name taken from the Name String File.

/rn/ in name string will be replaced with Replaced Name.

/pd/ in name string will be replaced with parent directory name of the current file or directory.

/wd/ in name string will be replaced with the current working directory name.

/l/ in name string will be replaced with line number from Name String File.

/la/ in name string will be replaced with actual line number from Name String File.

/dc/ in name string will be replaced with directory count.

/i/ in name string will be replaced with index.

/ir/ in name string will be replaced with reserved index.

/id/ in name string will be replaced with directory index (index inside a directory).

/idr/ in name string will be replaced with reserved directory index.

/-i/ in name string will be replaced with inverse index.

In general, -i ( /-ir/ /-idr/ etc..) in the above replacement rules (applies to indexes excluding line index) will mean inverse index conforming to their meaning.

Name String File

A file which contains a list of name string (one per line). Empty lines will be ignored and line number won't be counted. Actual line number (which counts the empty lines too) is available through name string rule: /la/. If the name string file path is passed through the option -nsfn , then it will expect the filenames to be null terminated instead of new line.

Search String

A string that is used to search for files with matching filenames against the search string. By default it is a regex if -ssF option is not used. It is generally in the form /regex/modifier , where regex is the regex to search for and available modifier is i which implies case insensitive search. If no modifier is used, regex format can be reduced to /regex/ or simply regex

Terminate multiple search strings with ; , e.g '/regex/modifier;/regex2/modifier2;...'

Also you can provide multiple search strings with repeated -ss and/or -ssf options and files with repeated -ss/f and/or -ssf/f options. These options can be combined together too.

Index Field Length

An integer value defining the field length of index. By default empty field will be filled with 0's. For example, if the value is 3, then index will be 001, 002, 003, etc.. Different filler (other than 0) can be provided with the -iff option.

Replaced Name

The name can be modified at runtime using replace string. replace string will be parsed to create a new Name String rule: /rn/ which can be used in Name String. If name string is not passed as argument, the new name of the file will be /rn/. Replaced Name is always generated from the old filename.

Replace String

Replace String modifies the filename and the modified filename is available through name string rule: /rn/ , If no Name String is provided, new name of the file will be the value of /rn/ by default. Replace String is a regex of the form: /search_part/replace_part/modifier where search_part is the regex to search for and replace_part is the string to replace with. Name string rules can be used in both search_part and replace_part in Replace String.

Regarding the replace_part , there are several special cases:

& will be taken as the entire match found by the regex (search_part).

\1, \2 etc.. is the back-references, i.e you can access captured groups with these back-references. Up-to two digits after the \ will be taken as a back-reference.

\c to convert to lowercase and \C to convert to uppercase. No other character is allowed in replace_part if \c or \C is used.

\p is the prefix (i.e., the part of the target sequence that precedes the match).

\s is the suffix (i.e., the part of the target sequence that follows the match).

to insert a & literally, use \& and for \ use \\.

Two modifiers are available: g and i ; g stands for global and replaces every instances of match found and i stands for case insensitive search (default is case sensitive).Replace String is always performed on old file name.

Example: '/video/Episode /i//gi' will replace every instances of 'video' with 'Episode index' i.e you will get new rname as: Episode 1..., Episode 2..., etc...

Terminate multiple replace strings with ; e.g '/search1/replace1/gi;/search2/replace2/i;...'

Also you can provide multiple replace strings with repeated -rs option and multiple files with repeated -rs/f options. These options can be combined together too.

Regex

Supported regexes are POSIX compliant basic & extended regex, grep, awk and egrep type regexes and the default ECMAScript regex. Change regex mode with -re or --regex option.

Only invalid characters for a file or directory name is the path delimiter and the null character (\0).

 

EXAMPLES

rnm filename -ns newfilename
renames from filename to newfilename
rnm filename -rs '/f/F/'
renames filename to Filename , i.e f is replaced with F.
rnm ./* -ns '/fn/ /i/'
/fn/ is full name and /i/ is the index i.e files and directories get indexed ( filename 1 , filename 2 , etc..).
rnm ./* -ns '/fn/ /i/' -fo
file only mode, i.e no directory will be renamed or indexed, unless depth is >0

LOGDIR

~/.neurobin/rnm

EXITSTATUS

0 on success

1 on failure

BUGREPORT

Report bugs to http://github.com/neurobin/rnm/issues

AUTHOR

MD. JAHIDUL HAMID
@github: http://github.com/neurobin
@bitbucket: http://bitbucket.com/neurobin

WEB

http://neurobin.github.io/rnm


Time: 17:49:58 GMT, October 15, 2015