rnm.1

.\"t
.\" Automatically generated by Pandoc 1.16.0.2
.\"
.TH "rnm" "1" "March 13, 2017" "rnm user manual" ""
.hy
.SH NAME
.PP
rnm \- Bulk rename utility
.SH SYNOPSIS
.PP
\f[B]rnm\f[] [\f[I]options\f[]] \f[I]file/paths\f[]
.SH DESCRIPTION
.PP
Renames files/directories in bulk.
Naming scheme (\f[I]Name String\f[]) can be applied or regex replace can
be performed to modify names dynamically.
It uses PCRE2 (revised version of PCRE) regex to provide search (and
replace) functionality.
.PP
It provides versatile options to modify names, delete/replace part of
it, indexing, case conversion, insert text, insert various file
information like modification time, access time, permission etc..,
insert parent directory names and many more.
.PP
File search functionality is provided with PCRE2 regex.
Fixed string search is also possible.
.PP
Operations (rename, changing names, search) are selective of file type
(directory, file, link).
.PP
Files can be sorted by name, modification time, access time, size, file
type (directory, file, link) etc..
.PP
It provides an undo functionality to move back unwanted rename
operations.
Different \f[B]rnm\f[] operations on different directory remember their
own undo history.
.PP
Simulations can be run instead of actual rename to view the potential
outcome as program output on terminal with the \f[I]\-sim\f[] option.
.SH USAGE
.IP
.nf
\f[C]
rnm\ \-ns\ name_string\ [other\-opts]\ file/path
rnm\ \-rs\ "/search/replace/mod"\ [other\-opts]\ file/path
rnm\ \-ns/f\ namestring/file/path\ file/path
\f[]
.fi
.SH OPTIONS
.TP
.B \-ns \f[I]name\-string\f[]
Name string.
This is generally the new name for the file.
Any part in this name string wrapped around with the path delimiter (/)
is parsed as a name string rule and the new name is formed accordingly.
See NAME STRING RULE for details.
.RS
.RE
.TP
.B \-ns/f \f[I]file\-path\f[]
Name string file.
File containing name strings per line.
It makes a new name string rule available, namely \f[I]/nsf/\f[], which
is generated by parsing the name string taken from the corresponding
line in the file.
Another additional rule \f[I]/l/\f[] becomes available for line number.
If \f[I]\-ns\f[] or \f[I]\-rs\f[] is not given, \f[I]/nsf/\f[] becomes
the new name.
This option adds a restriction on the number of files to be renamed
which is same as the number of non\-empty lines in the name string file
.
.RS
.RE
.TP
.B \-ns/fn \f[I]file\-path\f[]
Name String file.
This takes a null terminated Name String file, i.e a file where
filenames/name strings are terminated by null character (\f[I]\\0\f[])
instead of new line (\f[I]\\n\f[]).
.RS
.RE
.TP
.B \-sl \f[I]start\-line\f[]
Start Line number in name string file.
If start line is 0, it is changed to the highest line number possible in
the file.
For example, if you want to go from last line to first line, you can
pass start line as 0 and end line as 1.
Empty lines are always ignored but line numbers are counted.
Start line can be greater than end line, for example, start line 25 and
end line 12 would mean: go from line 25 to 12.
Default start line is 1.
.RS
.RE
.TP
.B \-l \f[I]start\-line\f[]
Same as \f[I]\-sl\f[]
.RS
.RE
.TP
.B \-el \f[I]end\-line\f[]
End line number in name string file to stop renaming from.
If end line is 0, it is changed to the highest line number possible in
the file.
For example, if you want to go from first line to last line in the file,
pass start line as 1 and end line as 0.
Empty lines are always ignored but line numbers are counted.
End line can be smaller than start line.
Default end line is the highest line number in the file.
.RS
.RE
.TP
.B \-linc \f[I]line\-increment\f[]
The amount line count will be incremented in each iteration for name
string file.
.RS
.RE
.TP
.B \-ss \f[I]search\-regex\f[]
Search string.
String that will be used to search for files with matching names.
This is generally a regex if not passed with \f[I]\-ssf\f[] option.
See SEARCH STRING for details.
This option can be given multiple times to add search strings.
.RS
.RE
.TP
.B \-ss/f \f[I]file\-path\f[]
Search string file.
A file containing search string per line.
This option can be given multiple times to add search strings.
.RS
.RE
.TP
.B \-ssf \f[I]fixed\-search\-term\f[]
Fixed search string (not treated as regex).
See SEARCH STRING for details.
This option can be given multiple times to add search strings.
.RS
.RE
.TP
.B \-ssf/f \f[I]file\-path\f[]
Search string file.
Contains fixed search string per line.
This option can be given multiple times to add search strings.
.RS
.RE
.TP
.B \-rs \f[I]replace\-string\f[]
A string in the form:
.RS
.IP
.nf
\f[C]
/regex/replace/modifier
\f[]
.fi
.PP
It performs regex replace on old filename to construct new name.
It uses PCRE2 regex.
After performing all the regex replace operations, the resultant string
is stored in the name string rule \f[I]/rn/\f[].
It can be used inside a name string or if name string is not given, this
will by default become the new name for the current file.
See REPLACE STRING for details.
This option can be given multiple times to add replace strings.
.RE
.TP
.B \-rs/f \f[I]file\-path\f[]
Replace string file.
A file containing replace string per line.
This option can be given multiple times to add replace strings.
.RS
.RE
.TP
.B \-si \f[I]start\-index\f[]
Start index.
.RS
.RE
.TP
.B \-i \f[I]start\-index\f[],
Same as \f[I]\-si\f[]
.RS
.RE
.TP
.B \-ei \f[I]end\-index\f[]
End index.
It works on directory index only.
When rename is occurring inside a directory for a depth value greater
than 0 or negative, directory index is limited to this end index.
When incrementing directory index hits this limit, all remaining
files/directories/links inside that directory are skipped.
All directories and their subdirectories will be subject to this
limiting value.
.RS
.RE
.TP
.B \-inc \f[I]increment\f[]
Increment value (floating point decimal).
The amount, index will be incremented or decremented in each iteration.
Decremented index is available through name string rule \f[I]/\-i/\f[],
\f[I]/\-id/\f[] etc..
.RS
.RE
.TP
.B \-if \f[I]INDEX\-FLAGS\f[]
This sets Index flags.
This is a \[aq]/\[aq] separated list of flags that will be used to
render the index within it\[aq]s text field.
The general format is:
.RS
.IP
.nf
\f[C]
\[aq]/flag1/flag2/flag3=value/...\[aq]
\f[]
.fi
.PP
Valued flags are set with \f[I]flag=value\f[] format.
Ex:
.IP
.nf
\f[C]
\[aq]/uppercase/filler=*/\[aq]
\f[]
.fi
See INDEX FLAGS for details.
.RE
.TP
.B \-ifl \f[I]index\-field\-length\f[]
Index field length.
Non occupied field will be filled with index field fillers (set with
\f[I]\-iff\f[]).
\f[I]iff\f[] is set to the character \f[I]0\f[] by default.
.RS
.RE
.TP
.B \-iff \f[I]index\-field\-filler\f[]
Non\-occupied field in index will be filled with a character set by this
option.
.RS
.RE
.TP
.B \-ifp \f[I]index\-field\-precision\f[]
Index is a floating point decimal (by default) value.
This sets the precision.
.RS
.RE
.TP
.B \-dp \f[I]depth\f[]
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 \f[I]0\f[], i.e directory contents will be ignored.
.RS
.RE
.TP
.B \-duh \f[I]seconds\f[]
Delete undo history older than the given seconds.
.RS
.RE
.TP
.B \-duhd \f[I]days\f[]
Delete undo history older than the given days.
.RS
.RE
.TP
.B \-fo
File only mode.
Only files are renamed (no directory or link).
Goes to subdirectory/s if depth (\f[I]\-dp\f[]) is greater than 0 or
negative.
.RS
.RE
.TP
.B \-do
Apply rename on directory only.
Goes to subdirectories if depth is greater than 0 or negative.
.RS
.RE
.TP
.B \-lo
Link only mode.
Goes to subdirectories if depth is greater than 0 or negative.
.RS
.RE
.TP
.B \-xd
Exclude directory.
Exclude any and all directories and their contents.
The depth value \f[I]\-dp\f[] will have no effect if this option is
given.
This is by default equivalent to file+link only mode if not overridden
by other options.
(You can read this option as cross\-d which probably makes more sense)
.RS
.RE
.TP
.B \-xf
Exclude file.
Depth value \f[I]\-dp\f[] is respected and goes to subdirectories if
depth is greater than 0 or negative.
This is by default equivalent to directory+link only mode if not
overridden by other options.
(You can read this option as cross\-f which probably makes more sense)
.RS
.RE
.TP
.B \-xl
Exclude link.
Depth value \f[I]\-dp\f[] is respected and goes to subdirectories if
depth is greater than 0 or negative.
This is by default equivalent to directory+file only mode if not
overridden by other options.
(You can read this option as cross\-l which probably makes more sense)
.RS
.RE
.TP
.B \-fl
Set follow link flag.
After passing this option, any file that is a link will be followed to
their original target.
If there are multiple links associated, only the end target (the
original) will be renamed.
This option must be passed before the file path that needs to be
followed.
Passing it after the file path will have no effect on the previous
files.
.RS
.RE
.TP
.B \-nfl
Unset follow link flag.
After this option is passed, previously set \f[I]\-\-follow\-link\f[]
flag will be unset and symbolic links after this point will not be
followed unless it gets overridden by another \f[I]\-fl\f[] option.
.RS
.RE
.TP
.B \-cd
Count directory in reserved index, regardless of other options.
Reserves indexes for directories even if it is file only or link only
mode.
.RS
.RE
.TP
.B \-cf
Count file in reserved index, regardless of other options.
Reserves indexes for files even if it is directory only or link only
mode.
.RS
.RE
.TP
.B \-cl
Count link in reserved index, regardless of other options.
Reserves indexes for links even if it is directory only or file only
mode.
.RS
.RE
.TP
.B \-s
Sort files in natural order (Human perceivable order).
This option can be modified to use other sorting methods.
For example: \f[I]\-s/g\f[] or \f[I]\-\-sort/general\f[] will sort the
file in general (alphabetic) order.
Available sorting methods:
.RS
.IP
.nf
\f[C]
\-s\ \ \ \ :\ default\ sort\ (natural\ sort)
\-s/g\ \ :\ general\ sort
\-s/n\ \ :\ natural\ sort
\-s/mt\ :\ sort\ according\ to\ file\ modification\ time\ (recent\ first)
\-s/at\ :\ sort\ according\ to\ file\ access\ time\ (recent\ first)
\-s/ct\ :\ sort\ according\ to\ file\ status\ change\ time\ (recent\ first)
\-s/sz\ :\ sort\ according\ to\ file\ size\ (larger\ first)
\-s/d\ \ :\ prioritize\ directory\ when\ sorting
\-s/f\ \ :\ prioritize\ file\ when\ sorting
\-s/l\ \ :\ prioritize\ link\ when\ sorting
\-s/r\ \ :\ reverse\ the\ order\ sorted\ by\ above\ methods
\-s/no\ :\ No\ sort
\f[]
.fi
.RE
.TP
.B \-y
Confirm Yes to all and suppress output for every file.
.RS
.RE
.TP
.B \-u
Undo rename.
Undo depends on working directory.
If an \f[B]rnm\f[] command is run from ~/somedir, to undo this operation
one must run \f[B]rnm\f[] from the same directory again or provide the
path with \f[I]\-up\f[] option.
Undo is a very aggressive operation, it bypasses all security check.
.RS
.RE
.TP
.B \-up
Undo rename from a given path.
After every successful rename (or undo), the undo path is set to the
working directory where \f[B]rnm\f[] is run from.
.RS
.RE
.TP
.B \-ups
Show available undo paths.
.RS
.RE
.TP
.B \-q
Quiet operation (speedy operation, includes \f[C]\-y\f[]).
.RS
.RE
.TP
.B \-qq
Suppress even error messages.
.RS
.RE
.TP
.B \-f
Force rename.
Enables renaming some restricted files except \f[I]/\f[].
.RS
.RE
.TP
.B \-ff
Double force.
Bypass all restrictions.
.RS
.RE
.TP
.B \-\-
If this option is passed, anything and everything after it will be taken
as file path.
Put all options before it.
.RS
.RE
.TP
.B \-h
Show help menu.
.RS
.RE
.TP
.B \-v
Show version info.
.RS
.RE
.TP
.B \-sim
This runs a simulation of rename instead of actual rename operation.
.RS
.RE
.SH PROPERTIES OF OPTIONS
.PP
\f[B]Options are not sequential\f[] (except \f[C]\-h\f[], \f[C]\-v\f[],
\f[C]\-fl\f[], \f[C]\-nfl\f[] \f[C]\-u\f[], \f[C]\-up\f[],
\f[C]\-ups\f[], \f[C]\-duh\f[], \f[C]\-duhd\f[]).
.PP
For example, the two commands below are the same:
.IP
.nf
\f[C]
rnm\ filepath\ \-ns\ name
rnm\ \-ns\ name\ filepath
\f[]
.fi
.PP
\f[B]Giving the same type of option multiple times is sequential.\f[] If
an option is capable of overloading, it adds the given values
sequentially, on the other hand, if the option can not be overloaded, it
is overwritten.
For example:
.IP
.nf
\f[C]
rnm\ \-rs\ \[aq]/_/\-/g\[aq]\ \-rs\ \[aq]/\-/./g\[aq]\ ./*
\f[]
.fi
.PP
In above, the first replace string is applied first replacing all
underscores to hyphen, then the second one replaces all hyphens to dot.
The final result is: All underscores and hyphens is replaced with dot.
The behavior is the same if they are glued together with semicolon as a
delimiter (\f[C]\-rs\ \[aq]/_/\-/g;/\-/./g\[aq]\f[])
.PP
\f[B]Options \-h, \-v, \-duh and \-duhd are treated as First come, first
served\f[] and possess the highest priority.
.PP
\f[B]The behavior of \-fl\f[] (\f[I]\-\-follow\-link\f[]) and
\f[B]\-nfl\f[] (\f[I]no\-follow\-link\f[]) option depends on their
position.
For example:
.IP
.nf
\f[C]
rnm\ \-ns\ \[aq]/fn/\ /id/\[aq]\ link1\ \-fl\ link2\ \\
\ \ \ \ \-nfl\ link3\ link4\ \-fl\ \ link5\ link6
\f[]
.fi
.PP
will rename the symbolic links as:
.IP "1." 3
\f[I]link1\f[] will itself be renamed, it won\[aq]t be followed
.IP "2." 3
\f[I]link2\f[] will be followed and its target will be renamed because
\f[I]\-\-follow\-link\f[] flag was \f[B]set\f[] before it.
.IP "3." 3
\f[I]link3\f[] and \f[I]link4\f[] won\[aq]t be followed because
\f[I]\-\-follow\-link\f[] flag was \f[B]unset\f[] by \f[I]\-nfl\f[]
before these links.
.IP "4." 3
\f[I]link5\f[] and \f[I]link6\f[] will be followed because
\f[I]\-\-follow\-link\f[] flag was \f[B]set\f[] again before these
links.
.PP
\f[B]Priority of undo related options:\f[] \f[C]\-ups\f[] >
\f[C]\-up\f[] > \f[C]\-u\f[].
.PP
\f[B]Options are case insensitive\f[], i.e \f[I]\-ssF\f[] and
\f[I]\-ssf\f[] are the same.
.SH FULLY SPECIFIED NAMES FOR OPTIONS
.PP
All of the shorthand option names have equivalent full names.
The use of either of them is the same, i.e all option or sub\-option
should be separated with space.
The rule \-\-someopt=value won\[aq]t apply, instead \f[B]rnm\f[] uses
the syntax \f[B]\-\-someopts value\f[].
The following table shows the full names corresponding to the shorthand
names:
.PP
.TS
tab(@);
l l.
T{
Opt name
T}@T{
Full name
T}
_
T{
\-ns
T}@T{
\-\-name\-string
T}
T{
\-ns/f
T}@T{
\-\-name\-string\-file
T}
T{
\-ns/fn
T}@T{
\-\-name\-string\-file\-null\-terminated
T}
T{
\-l
T}@T{
\-\-line
T}
T{
\-sl
T}@T{
\-\-start\-line
T}
T{
\-el
T}@T{
\-\-end\-line
T}
T{
\-linc
T}@T{
\-\-line\-increment
T}
T{
\-ss
T}@T{
\-\-search\-string
T}
T{
\-ss/f
T}@T{
\-\-search\-string\-file
T}
T{
\-ssf
T}@T{
\-\-search\-string\-fixed
T}
T{
\-ssf/f
T}@T{
\-\-search\-string\-fixed\-file
T}
T{
\-rs
T}@T{
\-\-replace\-string
T}
T{
\-rs/f
T}@T{
\-\-replace\-string\-file
T}
T{
\-i
T}@T{
\-\-index
T}
T{
\-si
T}@T{
\-\-start\-index
T}
T{
\-ei
T}@T{
\-\-end\-index
T}
T{
\-inc
T}@T{
\-\-increment
T}
T{
\-if
T}@T{
\-\-index\-flags
T}
T{
\-ifp
T}@T{
\-\-index\-field\-precision
T}
T{
\-ifl
T}@T{
\-\-index\-field\-length
T}
T{
\-iff
T}@T{
\-\-index\-field\-filler
T}
T{
\-dp
T}@T{
\-\-depth
T}
T{
\-duh
T}@T{
\-\-delete\-undo\-history
T}
T{
\-duhd
T}@T{
\-\-delete\-undo\-history\-day
T}
T{
\-fo
T}@T{
\-\-file\-only
T}
T{
\-do
T}@T{
\-\-directory\-only
T}
T{
\-lo
T}@T{
\-\-link\-only
T}
T{
\-xd
T}@T{
\-\-exclude\-directory
T}
T{
\-xf
T}@T{
\-\-exclude\-file
T}
T{
\-xl
T}@T{
\-\-exclude\-link
T}
T{
\-fl
T}@T{
\-\-follow\-link
T}
T{
\-nfl
T}@T{
\-\-no\-follow\-link
T}
T{
\-cd
T}@T{
\-\-count\-directory
T}
T{
\-cf
T}@T{
\-\-count\-file
T}
T{
\-cl
T}@T{
\-\-count\-link
T}
T{
\-s
T}@T{
\-\-sort
T}
T{
\-s/g
T}@T{
\-\-sort/general
T}
T{
\-s/n
T}@T{
\-\-sort/natural
T}
T{
\-s/no
T}@T{
\-\-sort/none
T}
T{
\-s/mt
T}@T{
\-\-sort/mtime
T}
T{
\-s/at
T}@T{
\-\-sort/atime
T}
T{
\-s/ct
T}@T{
\-\-sort/ctime
T}
T{
\-s/d
T}@T{
\-\-sort/directory
T}
T{
\-s/f
T}@T{
\-\-sort/file
T}
T{
\-s/l
T}@T{
\-\-sort/link
T}
T{
\-s/sz
T}@T{
\-\-sort/size
T}
T{
\-s/r
T}@T{
\-\-sort/reverse
T}
T{
\-y
T}@T{
\-\-yes
T}
T{
\-u
T}@T{
\-\-undo
T}
T{
\-up
T}@T{
\-\-undo\-path
T}
T{
\-ups
T}@T{
\-\-undo\-path\-show
T}
T{
\-q
T}@T{
\-\-quiet
T}
T{
\-qq
T}@T{
\-\-quiet\-quiet
T}
T{
\-f
T}@T{
\-\-force
T}
T{
\-ff
T}@T{
\-\-force\-force
T}
T{
\-h
T}@T{
\-\-help
T}
T{
\-v
T}@T{
\-\-version
T}
T{
\-sim
T}@T{
\-\-simulation
T}
.TE
.SH TERMINOLOGY
.PP
These are the technical terms that will be thrown around a bit for
convenience.
.SS RESERVED INDEX
.PP
Index will be incremented even if any file is skipped renaming in order
to reserve the index for that skipped file.
These are constructed by appending the \f[C]r\f[] character with the
index identifier, e.g \f[I]/ir/\f[], \f[I]/\-idr/\f[] etc..
.SS REVERSE INDEX
.PP
Decrementing index.
These are constructed by inserting a \f[I]\-\f[] before the index
identifier e.g \f[I]/\-i/\f[], \f[I]/\-id/\f[] etc..
.SS NAME STRING
.PP
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 some rules (Name String Rule).
(must be wrapped around with filepath delimiter \f[I]/\f[]).
.SS NAME STRING RULE
.PP
A name string rule starts and ends with a \f[I]/\f[] character, These
special forms are parsed and expanded to their special meaning.
For example \f[I]/i/\f[] would expand to file index.
.SS INDEX RULES
.IP "1." 3
\f[I]/i/\f[] : Index.
.IP "2." 3
\f[I]/ir/\f[] : Reserved index.
.IP "3." 3
\f[I]/id/\f[] : Directory index (index inside a directory).
.IP "4." 3
\f[I]/idr/\f[] : Reserved directory index
.IP "5." 3
\f[I]/\-i/\f[] : Inverse index.
.IP "6." 3
\f[I]/\-ir/\f[] : Inverse reserved index.
.PP
In general, \f[I]\-i\f[] in the above name string rules will mean
inverse index conforming to their meaning.
.SS COUNTERS
.IP "1." 3
\f[I]/dc/\f[] : Directory count
.IP "2." 3
\f[I]/l/\f[] : Line number from \f[I]Name String File\f[].
.PP
Base conversion, scientific conversion and Latin conversions are
applicable on these counters.
See EXTENDED INDEX RULES.
.SS EXTENDED INDEX RULES
.PP
\f[B]Base conversion:\f[]
.IP
.nf
\f[C]
/<rule>\-b<base>/
\f[]
.fi
.PP
For example, \f[I]/i\-b8/\f[] will convert the index to octal.
<base> can be 2 to 36.
.PP
\f[B]Scientific conversion:\f[]
.IP
.nf
\f[C]
/<rule>\-s/
\f[]
.fi
.PP
For example, \f[I]/i\-s/\f[] will convert the index to scientific form
(n.fE+\-p)
.PP
\f[B]Latin conversion:\f[]
.IP
.nf
\f[C]
/<rule>\-l/
\f[]
.fi
.PP
For example, \f[I]/i\-l/\f[] will convert the index to Latin form.
.PP
\f[B]Examples:\f[]
.IP
.nf
\f[C]
#indexing:
rnm\ \-ns\ \[aq]/fn/\ /i/\[aq]\ ./*
#indexing\ by\ directory:
rnm\ \-ns\ \[aq]/fn/\ /id/\[aq]\ ./*
#indexing\ with\ binary\ number
rnm\ \-ns\ \[aq]/fn/\ /id\-b2/\[aq]\ ./*
#indexing\ with\ scientific\ number
rnm\ \-ns\ \[aq]/fn/\ /id\-s/\[aq]\ ./*
#indexing\ with\ latin\ number
rnm\ \-ns\ \[aq]/fn/\ /id\-l/\[aq]\ ./*
\f[]
.fi
.SS FILENAME
.IP "1." 3
\f[I]/fn/\f[] : Full name of the file.
.IP "2." 3
\f[I]/n/\f[] : File name without extension.
.IP "3." 3
\f[I]/e/\f[] : File extension.
.IP "4." 3
\f[I]/rn/\f[] : Replaced Name, generated by replace strings.
.IP "5." 3
\f[I]/pd/\f[] : Parent directory name of the current file or directory.
.IP "6." 3
\f[I]/wd/\f[] : Current working directory name.
.IP "7." 3
\f[I]/nsf/\f[]: Name (or name string) from name string file.
.SS EXTENDED PD RULES
.PP
Its general format is
.IP
.nf
\f[C]
/pd<digits>\-<digits>\-<delimiter>/
\ \ \ \ \ \ \ \ \ or
/pd<from>\-<to>\-<delimiter>/
\f[]
.fi
.PP
It specifies a bidirectional range of parent directories.
.IP "1." 3
\f[I]/pd0/\f[] is the immediate parent directory name, \f[I]pd1\f[] is
the directory before \f[I]pd0\f[] and so forth.
.IP "2." 3
\f[I]/pd0\-2\-+/\f[] will expand by concatenating pd0 to pd2 and with
the \f[I]delimiter\f[] in\-between (e.g \f[I]dir0+dir1+dir2\f[]).
.IP "3." 3
\f[I]/pd2\-0\-+/\f[] will do the same as above but in reverse order
(\f[I]dir2+dir1+dir0\f[]).
.IP "4." 3
In place of \f[I]<digits>\f[] you can supply \f[I]e\f[] which generally
means the \[aq]end\[aq] i.e the farthest level available from the
immediate parent.
.IP "5." 3
In place of \f[I]<digits>\f[] you can also supply \f[I]w\f[] which means
the level of working directory.
.IP "6." 3
Any unavailable level of directory will be ignored and be replaced with
empty string.
.PP
\f[B]Examples:\f[]
.IP
.nf
\f[C]
#Appending\ parent\ directory\ names
#with\ space\ in\-between
rnm\ \-ns\ \[aq]/pd0\-e\-\ /\[aq]\ ./*
rnm\ \-ns\ \[aq]/pdw\-0\-\ /\[aq]\ ./*
\f[]
.fi
.SS INFO\-NAME STRING RULE
.PP
This name string rule provides basic information about a file, directory
or link.
The general format of this rule is:
.IP
.nf
\f[C]
/info\-prop\-op/
\f[]
.fi
.PP
where \f[I]info\-\f[] is the identifier for this rule, \f[I]prop\f[] is
the property name and \f[I]op\f[] is an optional entry which is used for
additional formatting.
Property names (\f[B]prop\f[]) are case insensitive.
.PP
\f[B]File time:\f[]
.TP
.B \f[I]mtime\f[]
File modification time.
\f[B]op\f[]: Time format (default \f[I]%d\-%m\-%Y\f[])
.RS
.RE
.TP
.B \f[I]mtime,GMT\f[]
File modification time in GMT.
\f[B]op\f[]: Time format (default \f[I]%d\-%m\-%Y\f[])
.RS
.RE
.TP
.B \f[I]atime\f[]
File access time.
\f[B]op\f[]: Time format (default \f[I]%d\-%m\-%Y\f[])
.RS
.RE
.TP
.B \f[I]atime,GMT\f[]
File access time in GMT.
\f[B]op\f[]: Time format (default \f[I]%d\-%m\-%Y\f[])
.RS
.RE
.TP
.B \f[I]ctime\f[]
File status change time.
\f[B]op\f[]: Time format (default \f[I]%d\-%m\-%Y\f[])
.RS
.RE
.TP
.B \f[I]ctime,GMT\f[]
File status change time in GMT.
\f[B]op\f[]: Time format (default \f[I]%d\-%m\-%Y\f[])
.RS
.RE
.PP
\f[B]Time Formats:\f[]
.PP
Time format string is used to specify an arbitrary date\-time format.
For example, \f[I]%d\-%m%\-Y\f[] would produce something like
\f[I]22\-01\-2017\f[].
This format string is exactly the same as the format string taken by
\f[C]strftime\f[] (3).
Some frequently used character sequences:
.IP \[bu] 2
%a, %A: week day name short and full respectively
.IP \[bu] 2
%b, %B: month name short and full
.IP \[bu] 2
%d: month day number
.IP \[bu] 2
%H: Hour in 24hr format
.IP \[bu] 2
%I: Hour in 12hr format
.IP \[bu] 2
%j: Day of the year (001\-366)
.IP \[bu] 2
%m: month number
.IP \[bu] 2
%M: Minute
.IP \[bu] 2
%p: AM/PM
.IP \[bu] 2
%P: am/pm (lowercase)
.IP \[bu] 2
%S: second in a minute
.IP \[bu] 2
%t: tab character
.IP \[bu] 2
%u: week day number (1\-7)
.IP \[bu] 2
%%: A literal % character.
.PP
You can find a lot more of these character sequences described in
details
here (http://man7.org/linux/man-pages/man3/strftime.3.html#DESCRIPTION).
.PP
\f[B]Example:\f[]
.IP
.nf
\f[C]
rnm\ \-ns\ \[aq]/fn/\ \-\ /info\-mtime\-%d\-%m\-%Y\ %I:%M:%S\ %p/\[aq]\ ./*
#The\ above\ appends\ modification\ time\ to\ the\ file\ names.
\f[]
.fi
.PP
\f[B]File size:\f[]
.TP
.B \f[I]size\f[]
Size of file.
\f[B]op\f[]: Unit (default: chosen according to size)
.RS
.RE
.TP
.B \f[I]blksize\f[]
Size of system I/O block.
\f[B]op\f[]: Unit (default: chosen according to size)
.RS
.RE
.TP
.B \f[I]blocks\f[]
Number of 512B blocks.
\f[B]op\f[]: N/A
.RS
.RE
.PP
\f[B]Other info:\f[]
.TP
.B \f[I]perm\f[]
File permission.
\f[B]op\f[]: Either \f[I]ls\f[] or \f[I]oct\f[].
.RS
.RE
.TP
.B \f[I]uid\f[]
Owner ID.
\f[B]op\f[]: N/A
.RS
.RE
.TP
.B \f[I]gid\f[]
Group ID.
\f[B]op\f[]: N/A
.RS
.RE
.TP
.B \f[I]dev\f[]
Device ID.
\f[B]op\f[]: N/A
.RS
.RE
.TP
.B \f[I]inode\f[]
Inode number.
\f[B]op\f[]: N/A
.RS
.RE
.TP
.B \f[I]mode\f[]
File mode.
\f[B]op\f[]: N/A
.RS
.RE
.TP
.B \f[I]nlink\f[]
Number of hard links.
\f[B]op\f[]: N/A
.RS
.RE
.PP
\f[B]Examples:\f[]
.IP
.nf
\f[C]
#Appending\ different\ file\ info\ to\ their\ names
rnm\ \-ns\ \[aq]/fn/\ size:\ /info\-size/\[aq]\ ./*
rnm\ \-ns\ \[aq]/fn/\ size:\ /info\-size\-1024/\[aq]\ ./*\ #size\ in\ KB
rnm\ \-ns\ \[aq]/fn/\ octperm:\ /info\-perm\-oct/\ lsperm:\ /info\-perm\-ls/\[aq]\ ./*
rnm\ \-ns\ \[aq]/fn/\ uid:\ /info\-uid/\[aq]\ ./*
\f[]
.fi
.SS NAME STRING FILE
.PP
A file which contains a list of name string (one per line).
Empty lines will be ignored but line number will be counted.
.PP
Each name string taken from this file is applied to each file, thus if
there\[aq]s 100 name strings in this file, their will be 100 rename
only.
All these name strings are parsed the same way as regular name strings
given with \f[I]\-ns\f[] option with an additional rule \f[I]/l/\f[]
(line number).
.PP
The generated/extracted name/namestring becomes available through the
name string rule \f[I]/nsf/\f[].
If an explicit \f[I]\-ns\f[] (or \f[I]\-rs\f[] and its equivalents)
option is not given on the command line, \[aq]/nsf/\[aq] is taken as the
name string by default i.e the new name will be the string expanded by
\f[I]/nsf/\f[].
.PP
A null terminated name string file is that one where name strings (i.e
filenames) are terminated with null character instead of newline
(\f[I]\\n\f[]).
These are generally binary files and can be generated with other tools.
.SS SEARCH STRING
.PP
A string that is used to search for files with matching filenames
against the search string.
By default it is a regex if \f[I]\-ssf\f[] option is not used.
It is generally in the form
.IP
.nf
\f[C]
/regex/modifier
\f[]
.fi
.PP
where \f[I]regex\f[] is the regex to search for and available modifiers
are \f[I]i\f[] (case insensitive), \f[I]f\f[] (file), \f[I]d\f[]
(directory), \f[I]l\f[] (link), \f[I]!\f[] (inverse search).
If no modifier is used, the regex format can be reduced to
\f[I]/regex/\f[] or simply \f[I]regex\f[].
.PP
Terminate search strings (\f[I]/regex/\f[] format only) with \f[I];\f[]
to provide multiple search strings, e.g
\f[I]\[aq]/s1/i;/s2/;/s3/\[aq]\f[].
This applies to fixed search strings as well.
.PP
Also you can provide multiple search strings with repeated \f[I]\-ss\f[]
and/or \f[I]\-ssf\f[] options and files with repeated \f[I]\-ss/f\f[]
and/or \f[I]\-ssf/f\f[] options.
These options can be mixed with each other too.
.PP
\f[B]Examples:\f[]
.IP
.nf
\f[C]
#rename\ only\ mp3\ and\ mp4\ files
rnm\ \-ns\ \[aq]/fn/\ /i/\[aq]\ \-ss\ \[aq]/.*\\.mp(3|4)$/\[aq]\ ./*
#rename\ everything\ excluding\ mp3\ and\ mp4\ files
rnm\ \-ns\ \[aq]/fn/\ /i/\[aq]\ \-ss\ \[aq]/.*\\.mp(3|4)$/!\[aq]\ ./*
#rename\ file\ with\ .video\ in\ their\ names
#\ (fixed\ string\ search)
rnm\ \-ns\ \[aq]/fn/\ /i/\[aq]\ \-ssf\ \[aq].video\[aq]\ ./*
\f[]
.fi
.SS INDEX FIELD LENGTH
.PP
An integer value defining the field length of index.
By default empty field will be filled with 0\[aq]s.
For example, if the value is \f[I]3\f[], then indexes will be
\f[I]001\f[], \f[I]002\f[], \f[I]003\f[], etc..
Different filler (other than 0) can be provided with \f[I]\-iff\f[]
option.
.SS REPLACED NAME
.PP
The name can be modified at runtime using replace string.
Replace string will be parsed to create a new \f[I]Name String\f[] rule:
\f[I]/rn/\f[] which can be used in \f[I]Name String\f[].
If name string is not passed as argument, the new name of the file will
be \f[I]/rn/\f[].
\f[I]Replaced Name\f[] is always generated from the old filename (even
when name string file is given).
.SS REPLACE STRING
.PP
\f[I]Replace String\f[] is of the form:
.IP
.nf
\f[C]
/regex/replace/modifier
\f[]
.fi
.PP
where \f[I]regex\f[] is the regex to search for and \f[I]replace\f[] is
the string to replace with.
\f[I]Name String\f[] rules are available in \f[I]regex\f[] and
\f[I]replace\f[] part in Replace String.
.PP
Special character sequences for \f[I]replace\f[] part:
.IP "1." 3
\f[I]&\f[] will be taken as the entire match found by the
\f[I]regex\f[].
.IP "2." 3
\f[I]\\1\f[], \f[I]\\2\f[] etc..
are the captured groups.
If you want to isolate a captured group, wrap it around with
\f[I]{}\f[].
For example, if you want to put a digit (2) after captured group
\f[I]\\1\f[], you can\[aq]t use it like \f[I]\\12\f[].
\f[I]\\12\f[] will mean \f[I]12th\f[] captured group not \f[I]\\1\f[]
appended with a digit (1).
In this case isolate the captured group with \f[I]{}\f[] i.e
\f[I]\\{1}2\f[].
.IP "3." 3
Named captured group can be accessed as \f[I]\\{name}\f[].
.IP "4." 3
\f[I]\\c\f[] will convert the matched string to lowercase, and
\f[I]\\C\f[] will convert it to uppercase.
No other character is allowed in replace part if this is used.
You can still concatenate different replace strings with \f[I];\f[]
(semicolon).
.IP "5." 3
to insert a \f[I]&\f[] literally, use \f[I]\\&\f[] and for \f[I]\\\f[]
use \f[I]\\\\\f[].
.IP "6." 3
Modifiers are \f[I]i\f[] (case insensitive), \f[I]g\f[] (global),
\f[I]f\f[] (file), \f[I]d\f[] (directory), \f[I]l\f[] (link).
.PP
\f[I]Replace String\f[] is always performed on old file name (even when
name string file is given).
.PP
You can provide multiple replace strings with repeated \f[I]\-rs\f[]
option and multiple file with repeated \f[I]\-rs/f\f[] options.
These options can be mixed with each other too.
.PP
Multiple replace strings can also be given by terminating each
individual replace strings with \f[I];\f[] (semicolon):
.IP
.nf
\f[C]
rnm\ \-rs\ \[aq]/.*_/\\C/gi;/\-/\ /g;/#/\@/g\[aq]\ ./*
\f[]
.fi
.PP
\f[B]Examples:\f[]
.IP
.nf
\f[C]
#convert\ to\ uppercase
rnm\ \-rs\ \[aq]/.*/\\C/\[aq]\ ./*
#convert\ to\ lowercase
rnm\ \-rs\ \[aq]/.*/\\c/\[aq]\ ./*
#replace\ all\ \@\ with\ \-\ in\ the\ names
rnm\ \-rs\ \[aq]/\@/\-/g\[aq]
#Treat\ files\ and\ directories\ differently
rnm\ \-rs\ \[aq]/\@/\-/gf;/#/\@/gd;\[aq]
#the\ above\ will\ replace\ all\ \@\ in\ file\ (not\ directory)
#names\ to\ \-\ and\ all\ #\ in\ directory\ names\ to\ \@
\f[]
.fi
.SS INDEX FLAGS
.IP \[bu] 2
\f[I]uppercase\f[] : means uppercase.
.IP \[bu] 2
\f[I]showpoint\f[] : show point regardless if it\[aq]s an integer or
floating point value.
.IP \[bu] 2
\f[I]showbase\f[] : means show base (Hex or Oct).
.IP \[bu] 2
\f[I]showpos\f[] : show + sign for positive numbers.
.IP \[bu] 2
\f[I]right\f[] : adjust right.
.IP \[bu] 2
\f[I]left\f[] : adjust left.
.IP \[bu] 2
\f[I]internal\f[] : adjust internal.
.IP \[bu] 2
\f[I]precision\f[] : set precision.
Used as \f[C]precision=value\f[]
.IP \[bu] 2
\f[I]length\f[] : sets length.
Used as \f[C]length=value\f[]
.IP \[bu] 2
\f[I]filler\f[] : sets filler.
Used as \f[C]filler=value\f[]
.SS MODIFIERS
.IP "1." 3
\f[I]i\f[]: case insensitive match or replace.
.IP "2." 3
\f[I]g\f[]: global replace
.IP "3." 3
\f[I]f\f[]: True if it\[aq]s a file, otherwise false.
.IP "4." 3
\f[I]d\f[]: True if it\[aq]s a directory, otherwise false.
.IP "5." 3
\f[I]l\f[]: True if it\[aq]s a link, otherwise false.
.IP "6." 3
\f[I]!\f[]: inverse search.
.PP
The \f[I]f\f[], \f[I]d\f[] and \f[I]l\f[] modifiers are ORed when
combined.
.SS EXAMPLES:
.IP
.nf
\f[C]
rnm\ file\ \-ns\ new_file
rnm\ file\ \-rs\ "/f/F/"
#\-do\ forces\ Directory\ only\ mode
rnm\ folder\ \-ns\ "New\ Folder"\ \-do
rnm\ ./New*/*\ \-ns\ /i/.ext
#This\ will\ go\ inside\ the\ New\ Folder\ directory
rnm\ "./New\ Folder"\ \-ns\ /id//dc/.ext\ \-dp\ 1\ \-fo
#\ \-dp\ \-1\ (infinite\ depth)
rnm\ "./New\ Folder"\ \-ns\ /id//dc/.ext\ \-dp\ \-1\ \-fo
rnm\ ./New*\ \-ns\ /id/.ext\ \-ss\ "regex"
rnm\ \-ns/f\ filepath\ \-ns\ /n//id/.ext
rnm\ \-ns/f\ filepath
\f[]
.fi
.PP
\f[B]Only invalid characters for a file or directory name is the path
delimiter (/) and the null character (\f[I]\\0\f[]).\f[]
.SH THINGS TO CARE
.IP "1." 3
All options should always be separated by space.
For Example: \f[I]\-vy\f[] won\[aq]t mean two option \f[I]\-v\f[] and
\f[I]\-y\f[], rather it will mean a single option \f[I]\-vy\f[].
.IP "2." 3
Any dangling argument with \f[I]\-\f[] at beginning will be treated as
an option and produce error if invalid.
.IP "3." 3
If filename/path argument may include \f[I]\-\f[] at the beginning, use
\f[I]\-\-\f[] to make all the arguments after this option as paths/names
(not options).
.IP "4." 3
If you run \f[C]rnm\ .\ \-ns\ something\f[] or
\f[C]rnm\ ./\ \-ns\ something\f[], your current directory will be
renamed (be careful).
.IP "5." 3
This is a dangerous tool like \f[C]rm\f[], so use with care.
If you make a mistake and do some unwanted rename, run \f[C]rnm\ \-u\f[]
to undo (before running any more \f[B]rnm\f[] command).
.IP "6." 3
Pass all regex like strings within quotes even if they don\[aq]t contain
any white space.
.IP "7." 3
To pass a filename that resembles an option, use \f[C]\&./\f[], i.e
\f[C]\&./\-ns\f[] to pass a file named \f[C]\-ns\f[] in the current
directory.
Or you can use the \f[C]\-\-\f[] option to make it a non\-option
argument; in that case make sure to pass all "Option" arguments before
\f[C]\-\-\f[], because everything after \f[C]\-\-\f[] will be taken as
file path/s.
.IP "8." 3
A common mistake is to pass files like this:
\f[C]rnm\ \-ns\ \[aq]something\[aq]\ *\f[], it will work as long as no
file names contain \f[I]\-\f[] at the beginning, a safer approach is
\f[C]rnm\ \-ns\ \[aq]something\[aq]\ ./*\f[]
.SH LIMITS
.PP
\f[B]Maximum length of file name :\f[] FILENAME_MAX
.PP
\f[B]Default latin fallback :\f[] 55555.
After this value Latin conversion will fall back to decimal.
You can override this with \f[I]\-if\f[] option by setting
\f[I]/latin\-fallback=6666/\f[] (or some other value).
Big Latin number may produce much larger name which in turn may give you
error due to limit on length of file names.
.SH LOG DIR
.PP
~/.local/share/neurobin/rnm
.SH EXIT STATUS
.PP
.TS
tab(@);
l l.
T{
Status
T}@T{
Details
T}
_
T{
0
T}@T{
Success
T}
T{
1
T}@T{
Failure
T}
T{
2
T}@T{
Interrupt
T}
T{
3
T}@T{
Unsafe termination
T}
T{
4
T}@T{
Unknown termination
T}
.TE
.SH BUG REPORT
.PP
<https://github.com/neurobin/rnm/issues>
.SH AUTHORS
Md Jahidul Hamid <https://github.com/neurobin>.