This tool renames files and directories based on patterns.
Patterns
========
There are two kinds of patterns: literal, variable. The latter ones are
surrounded by a pair of brackets i.e.: []. The patterns which handle string
values support the change of case:
* x - unchanged
* XX - upper case
* Xx - first character upper case, others lower case
* xx - lower case
Some patterns support limiting the action to a particular part of the file
name. In this cases the selector character is located after the pattern character.
For example:
[Xe] - limits the extraction to the extension
The pattern character always sets the casing, not the selector character.
Selector characters are:
* f - whole file name
* n - name without extension
* e - extension
The following patterns are available:
Full file name
--------------
Pattern: [F], [FF], [ff], [Ff]
Description: returns the whole file name
File name
---------
Pattern: [N], [NN], [nn], [Nn]
Description: returns the file name without the extension
Extension
---------
Pattern: [E], [EE], [ee], [Ee]
Description: returns the extension
Counters
--------
There are two types of counters: string, integer. Multiple different counters
(with different properties) can be specified in a pattern. It is possible to
use one counter several times in a pattern, it will be incremented only
once. The general format of the pattern is:
[Cid:format,step]
Pattern: [C]
Description: returns a counter value, counting from 1, with the default
format
Pattern: [C:format]
Description: the format influences multiple properties. First it chooses
between numerical, and character counters. If the format is all
digits it will be a numerical, otherwise it will be a character
counter. In both cases it sets the start value of the counter
as well.
In the case of a numerical counter the format sets the padding
length as well. For example: 0001, the counter will be padded
with nulls to a length of 4.
In the case of character counters it is possible to set the
character case as usual, with varying the casing of the C.
Examples: * [C:2] start from 2 do not change formatting
* [C:001] start from one, pad the result with 0 to a length of 3
* [C:a] use a character counter
* [CC:A] use a character counter, with upper case characters
* [Cc:bb] use a character counter, start from bb, first character
is upper case others lower case
Pattern: [C:format,steps]
Description: format is the same as before. The steps describe the difference
between two counts
Pattern: [Cid]
Description: id is a numerical value, which gives a name to the counter
allowing multiple counters to co-exist. Only the first
occurence of the counter has to be configured.
Examples: * [C1:001][C2:a][C1] the first counter is a numerical one,
with a padded format. The second is a
character counter. The first counter is
used again, here only the id is given.
Extraction
----------
Pattern: [X:start]
Description: returns the substring denoted by start. Start is a one based
index. If start is negative, then the index is from the end of
the string. If the start is past or before the string, then no
or all characters will be returned. The extractor pattern
supports selector characters.
Examples: * [X:3] return the substring of the file name from
the third character
* [X:-2] return the substring from the second character
from the end of the string
* [Xxe:2] return the from the second character of
the extension, with the first letter upper cased the
others lower cased
Patter: [X:start,length]
Description: returns the substring denoted by start with the given length.
If the length is negative, then the substring before start with
the given length will be returned.
Modification time
-----------------
Pattern: [D]
Description: returns the modification date of the file. Format is: YYYYmmdd
Pattern: [D:format]
Description: returns the modification time with the given format.
The formatting characters are the same as for strftime().
Collisions
==========
There are three types of collisions: existing files, new names colliding, and
new names colliding with old names. In show mode these three types are
displayed along with the old and new names. The following symbols are used:
* - existing files would be overwritten
! - the new name of the file is the same as the new name of some other file(s)
= - the new name of the file is the same as the old name of some other file
Existing files will not be overwritten, unless the force command line option
is given.
If a new name collision is detected the program exits, as this is certainly
not the desired outcome.
If an old name collision is detected, the application tries to solve this by:
re-ordering the file renames, inserting temporary renames given there is a
circular dependency between the renames.
Options
=======
-h --help
Usage information.
-s --show-only
Only show renames.
-l FILE --log=FILE
Log rename actions to file. The format of the file is:
[old name]:[new name]
-i FILE --input=FILE
Load renames from file. The file format should be the same as
the log is writing.
-u FILE --undo=FILE
Undo renames from a log file. The old names in the files will
be used as new, and the new as old names.
-f --force
Force renaming. Existing files will be overwritten.