NAME
----
**tren** - Advanced File Renaming
SYNOPSIS
--------
::
tren.py [-acbeghpqtvx] [-T template] [-l string] [-r old=new]... file|dir file|dir ...
DESCRIPTION
-----------
.. WARNING:: **tren** is a powerful file and directory renaming tool.
Be **sure** you know what you're about to do. If you're
not, run the program in test mode (invoke with the ``-t``
option) to see what could happen. You have been warned!
**tren** is a general purpose file and directory renaming tool. Unlike
commands like ``mv``, **tren** is particularly well suited for
renaming *batches* of files and/or directories with a single command
line invocation. **tren** eliminates the tedium of having to script
simpler tools to provide higher-level renaming capabilities.
**tren** will not allow you to rename a file or directory if one with
the new name already exists. Such attempts will cause no change to the
file or directory being processed and a warning message will be
displayed. This is intentional to force you to manually rename or
remove the file or directory that would have been clobbered by a
rename.
**tren** supports two kinds of renaming operations, *String Substitution*
and *Rename By Template*.
String Substition
-----------------
String substitution is handy when you have files and directories
that have a common set of characters in them you'd like to change.
For instance::
tren.py -r .Jpeg=.jpg *.Jpeg
would rename all files (or directories) whose names contained the string
``.Jpeg`` and replace it with ``.jpg``. It's important to realize that
such a substitution takes place *anywhere* in the file name, not just at
the end or "extension" (as it is called in Windows). You can limit
the replacement to just the "name" (``-b``) or "extension" (``-e``)
portions of the filename.
By default, only the first instance of the string is replaced in the
name, but you can use the ``-g`` option to replace *all* instances
of the old string with the new one.
Ordinarily **tren** treats both the old string you specify with
the ``-r`` option *literally*. However, it is sometimes handy
to be able to write a regular expression to specify what you
want replaced. If you specify the ``-x`` option, **tren** will
treat your old string as a Python style regex, compile it (or
try to anyway!) and use it to select which strings to replace.
This makes it much easier to rename files that have repeated
characters or patterns, and groups of files that have similar,
but not idential strings in their names you'd like to replace.
Rename By Template
------------------
It is sometimes useful to be able to take a group of files/directories
whose names have nothing in common and impose a common naming scheme
on them. For example, suppose you and your friends pool your vacation
photos but each of your cameras uses a slightly different naming
scheme. You might want to just reorder them by the date and time each
picture was taken, for example. That way you end up with one
coherent set of named and numbered files. You might have
something like this::
DSC002.jpg (Bob's camera, taken 1-5-2010 at noon)
dc0234.Jpg (Mary's camera, taken 1-5-2010 at 8am)
032344.jpeg (Sid's camera, taken 1-3-2010 at 4pm)
It would be nice to get these in order somehow.
*Rename By Template* provides this ability. Given a list of files,
you apply a "template" or pattern to be used when renaming them. This
template is nothing more than a string containing both literal
text and so-called *renaming tokens* built into **tren**.
There's a whole section later in this document on template
construction and the use of renaming tokens, but here's a simple
example to illustrate the general idea using the files above::
tren.py -T /D/-MyVacation-/0001/.jpeg *.jp*
This would rename all the files in the current directory ending with
``.jp*``. The ``/D/`` would be replaced with the *date* the picture
was taken. The ``/0001/`` refers to a *starting sequence number* to
uniquely identify pictures taken on the same date. The other strings
in the template, ``-MyVacation-`` and ``.jpeg``, are inserted
*literally* in the final file names. After we ran this command, the
files above would end up with these names::
20100103-MyVacation-0001.jpeg (Sid's)
20100105-MyVacation-0001.jpeg (Mary's)
20100105-MyVacation-0002.jpeg (Bob's)
Notice that the files taken on the same date have been sequenced by
the time-of-day they were taken because we included the ``/0001/``
renaming token in our pattern.
There are many other renaming tokens and ways to construct
all manner of clever templates. These are discussed below in the
section entitled `TEMPLATE CONSTRUCTION`_.
Ordinarily the template text *replaces* the *entire* existing
filename. You can limit the replacement to either the "name" (``-b``)
or "extension" (``-e``) portions of the filename. Instead of
replacing the existing name, extension, or both, you can also choose
to append (``-a``) or prepend ``-p`` the template text.
OPTIONS
-------
-T template Rename by template.
(*Default*: Rename via string replacement.)
Use a template to rename the file. This is discussed in
detail in the `TEMPLATE CONSTRUCTION`_ section below.
-a Append the template text to the existing file or directory
name.
(*Default*: Replace the file or directory name with the
template text.)
-b Only perform renaming within "name" portion of file
or directory name.
(*Default*: Substitute within the entire file or directory name)
Many applications use the suffix of a filename to indicate the
contents or type of file. By default, **tren** does renaming
in the entire filename *including* the extension. For example
doing this::
tren.py -r eg=ug peg.jpeg
Renames the file to ``pug.jpug`` .. probably not what you want.
The ``-b`` option tells **tren** to only perform string renaming
in the actual "name portion" of the filename thereby
cirumventing problems like this::
tren.py -b -r eg=ug peg.jpeg # Renames file to pug.jpeg
-c Collapse case when doing string substitution.
(*Default*: Search for string to replace is case sensitive.)
When looking for a match on the old string to replace,
**tren** will ignore the case of the characters found
in the filename. For example::
tren.py -c -r Old:NEW Cold.txt fOlD.txt
This renames both files to ``CNEW.txt`` and ``fNEW.txt``
respectively. Notice that the new (replacement) string's case
is preserved.
-e Only perform renaming within "extension" portion of
or directory name.
(*Default*: Substitute within the entire file or directory name)
This option is the inverse of ``-b``. It instructs **tren**
to do the requested renaming *only* in the filename
"extension" not on the file name portion. For example::
tren.py -e -r pe=p peg.jpeg # Renames file to peg.jpg
-g Replace all instances (greedy replace) of the old string
with the new.
(*Default*: Only the first matching string is replaced.)
Ordinarily, **tren** only replaces the single *leftmost*
instance of a string in the entire filename (default), the name
portion (``-b``) or the extension (``-e``). If you want
*all* instances of a particular string replaced, use this
option to enable "greedy" replacement::
tren.py -g -r p:P pop.txp # Renames file to: PoP.txP
-h Print help information.
-l string File "extension" delimiter string.
(*Default*: ".")
**tren** has to know what separates the "name" from the
"extension" in a filename. By default, it uses the
rightmost ``.`` character. You can change it with this
option to "divide" the filename into name and extension
for renaming purposes, using any string you like. This
is particularly helpful with ``-b`` and ``-e`` options::
tren.py -b -l .long.txt -r long:short long.long.txt.long.txt.foo
This would rename the file to::
short.short.txt.long.txt.foo
Notice that **tren** looks for the *rightmost* instance
of the separator to split the whole filename into name
and extension components. Notice also that when you do
this, no renaming of characters *within* the separator
takes place.
-p Prepend the template text to the existing file or directory
name.
(*Default*: Replace the file or directory name with the
template text.)
-q Quiet mode, do not show progress.
(*Default*: Display progress)
Ordinarily, **tren** displays what it is doing as it
processes each file. If you prefer to not see this
"noisy" output, use the ``-q`` option. Note that this
does not suppress warning and error messages.
This option is ignored when running in test mode (``-t``).
-r <old=new> Replace "oldstring" with "newstring" in file names.
Use this option to specify which strings you
want to replace in each file name. These strings
are treated literally unless you also invoke
the ``-x`` option.
You can have multiple instances of this option on
your **tren** command line::
tren.py -e old:new -e txt:doc old-old.txt
This renames the file to::
new-old.doc
By default, **tren** only replaces the first
(leftmost) instance of the old string with the new.
This option's behavior is modified by the ``-b``,
``-c``, ``-e``, ``g``, ``l``, and ``x`` options.
If you need to use the ``=`` symbol *within* either
the old or new string, simply escape it: ``\=``
-t Test mode, don't rename, just show what the program *would* do
(ignores -q).
**tren** is very powerful and capable of doing nasty things to
your files (like making a file disappear when another one is
renamed over it). For this reason, it is helpful to test
your **tren** commands before actually using them. With this
option enabled, **tren** will print out diagnostic information
about what your command *would* do, *without actually doing it*.
-v Print detailed program version information and exit.
-x Treat the old string in a ``-r`` replacement as a Python
style regular expression for matching purposes.
(*Default*: Treat the old string as literal text)
String substitution arguments to the ``-r`` option are usually
understood to be taken literally. There are, however, instances
where this is tedius to do. Say you have a set of files
that are similar, but not idential in name, and you want to
rename them all::
sbbs-1.txt
sbbbs-2.txt
sbbbbbbbbs-3.txt
Suppose you want to rename them, replacing two or more instances
of ``b`` with ``X``. It is tedious to have to write a separate
``-r old:new`` string substitution for each instance above.
This is where regular expressions can come in handy. When you
invoke the ``-x`` option, **tren** understands this to mean that
the ``old`` portion of the replacement option is to be treated as
a *Python style regular expression*. That way, a single string
can be used to match many cases::
tren.py -x -r bb+:X *.txt
This renames the files to::
sXs-1.txt
sXs-2.txt
sXs-3.txt
**tren** only accepts Python style regular expressions. Anything
else will cause an error message to be displayed.
Because Python regular expressions can make use of the ``=``
symbol, you need a way to distinguish between an ``=`` used in a
regular exression and the same symbol used to separate the old
and new operands for the ``-r`` option. Where this symbol needs to
appear in a regular expression, it has to be escaped like this:
``\=``.
TEMPLATE CONSTRUCTION
---------------------
Template based renaming is used when you want to impose a naming
"pattern" on a group of files or directories. This is most useful
when the existing filenames have little or nothing in common. In such
situations, there's often no direct way to use string substitutions to
order the names in some coherent way.
A "template" is built from literal text and *renaming tokens*. These
tokens are delimited by the ``/`` character. **tren** replaces these
tokens with corresponding information (see descriptions below) to
produce a final "template text". The template text is the actual
string used to either replace the existing file or directory name (or
just the "name" or "extension" portions, depending on which options
you've selected) or to be appended or prepended to the name.
Currently, **tren** defines a number of renaming tokens.
File Attribute Renaming Tokens
------------------------------
These tokens are derived from information about the file or
directory being renamed.
``/D/ File or directory creation date``
This token is replaced with the date of creation
of the file or directory being renamed. It is
in ``YYYMMDD`` format.
``/E/ Original File Extension``
This token is replaced the "extension" portion of the file
or directory before renaming. This does not include the
extension separator string.
``/F/ Original File Name``
This token is replaced the "name" portion of the file or
directory before renaming.
.. NOTE:: Notice that there is no token for the *whole* filename
because you can always synthesize it with ``/F/./E/``
``/G/ File or directory primary group name``
This token is replaced with the name of the
primary group to which the file belongs.
``/I/ File or directory creation date``
This token is replaced with the date of creation of the
file or directory being renamed. It is similar to ``/D/``
except it is in ISO format, ``YYYY-MM-YY``.
``/S/ File or directory size``
This token is replaced with a numeric string
that indicates the size of the file or directory
in bytes.
``/T/ File or directory creation time``
This token is replaced with the time of creation
of the file or directory being renamed. It is
in ``HH:MM:SS`` format.
``/U/ File or directory owner name``
This token is replaced with the name of the
file or direcotry's owner.
Sequence Renaming Tokens
------------------------
Sometimes it's useful to rename files or directories based on some
*property they possess* like the date or time of creation, the size of
the file, who owns it, and so on. That's the idea behind the ``/D/``,
``/T/``, and ``/S/`` renaming tokens described in the previous section.
An extension of this idea is to *order all the files being renamed*
based on one of these parameters. For instance, instead of actually
embedding the date and time of creation in a file or directory name,
you might want to order the files from oldest to newest with a naming
convention like::
file-1.txt
file-2.txt
file-3.txt
This guarantees uniqueness in the final name and also sees to it that
a sorted directory listing will show you the files or directories in
the order you care about.
This is the purpose of *sequence renaming tokens*. They give you
various ways to create sequences that can be embedded in the final
file or directory name.
General Format Of Sequence Renaming Tokens
------------------------------------------
Sequence renaming tokens consist of three descriptive components and
have the following general format::
/<ordering flag><type><counting pattern>/
where,
ordering flag:
+ ascending
- descending
type:
D sequence on file creation date & time
O sequence on the command line file order
S sequence on file size
T sequence on file creation time within a given day
Count Pattern Format
--------------------
The counting pattern is used to specify two things: The width of the
sequence string, and the starting value for the sequence. Examples::
0001 -> 0001, 0002, 0003, ...
0000 -> 0000, 0001, 0002, ...
03 -> 03, 04, 05, ...
You do not have to use a ``0`` to indicate the sequence width. You
can use *any* padding characters you like. **tren** only cares about
the width of the field and will "consume" your padding characters as
the count increases.::
xxx3 -> xxx3, xxx4, xxx5, ... 9999, xxx3, xxx4, ...
-+8 -> -+8, -+9, -10, -11, ... 999, -+8, -+9, ...
You are not restricted to numbers in a counting pattern. Letters may
also be used. **tren** will preserve the case you specify in the
template when creating sequences like this::
000a -> 000a, 000b, 000c, ... zzzz, 000a, ...
---Y -> ---Y, ---Z, --AA, ... ZZZZ, ---Y, ---Z, ...
Notice that when a sequence "rolls over", the next value is the
*initial sequence value you specified*.
System Related Renaming Tokens
------------------------------
These tokens are derived from the underlying operating system
and runtime environment.
``/$ENV/ Environment variable``
This token is replaced with the value of
the environment variable ``$ENV``. If
that variable does not exist, the token
is replaced with an empty string.
``/\cmd\`/`` Arbitrary command execution``
This token is replaced with the text
returned by executing the ``cmd`` command.
EXAMPLES
--------
Here are some common examples of **tren** in action - the resulting
file name(s) shown to the right as a comment. Study each example
carefully. Small subtleties are introduced in various
adjacent examples to illustrate diffent features of **tren**:
Simple rename::
tren.py -r old=New fold.txt log.old # fNew.txt log.New
Change file "name"::
tren.py -b -r old=New fold.txt log.old # fNew.txt log.old
Change file "extension"::
tren.py -e -r old=New fold.txt log.old # fold.txt log.New
Rename all instances of a given string::
tren.py -g -r bin=Bin binary_bin.binbin # Binary_Bin.BinBin
Rename, ignoring case::
tren.py -c -r bin=BIN Binary_bIN.txt # BINary_bIN.txt
Rename multiple strings at once::
tren.py -r log:txt -r New:old New.log # old.txt
Rename using regular expressions::
tren.py -x -r a+=a Saaaaaaaally.doc # Sally.doc
Rename a file containing the ``=`` symbol::
tren.py -r a\=b=c\=d a=b.txt # c=d.txt
Use template::
tren.py -T /I/ file.1 # 2010-01-12
Use template to change file "name"::
tren.py -b -T /I/ file.1 file.2 # 2010-01-12.1 2010-01-12.2
Use template to change file "extension"::
tren.py -e -T /D/ file.1 # file.20100112
Append template text::
tren.py -a -T ./D/ file.1 # file.1.20100112
Prepend template text::
tren.py -p -T /D/- file.1 # 20100112-file.1
Get help::
tren.py -h
Print out detailed version information::
tren.py -v
OTHER
-----
You must have a reasonably current version of Python installed.
BUGS AND MISFEATURES
--------------------
None known as of this release.
COPYRIGHT AND LICENSING
-----------------------
**tren** is Copyright (c) 2010 TundraWare Inc.
For terms of use, see the ``tren-license.txt`` file in the
program distribution. If you install **tren** on a FreeBSD
system using the 'ports' mechanism, you will also find this file in
``/usr/local/share/doc/tren``.
AUTHOR
------
::
Tim Daneliuk
tren@tundraware.com
DOCUMENT REVISION INFORMATION
-----------------------------
::
$Id: tren.rst,v 1.121 2010/01/18 23:43:36 tundra Exp $
You can find the latest version of this program at:
http://www.tundraware.com/Software/tren
tundra