NAME
----

**tren** - Advanced File Renaming

SYNOPSIS
--------

::

    tren.py [-beghqtvwx] [-l string] [-m template] [-r old=new]... file|dir file|dir ...


DESCRIPTION
-----------

.. WARNING::
   **tren** is a powerful file and directory renaming tool.  It is 
   entirely possible to clobber files by renaming one file  so as to
   delete another one with that same name.  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** 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 -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 filename, not just at
the end or "extension" (as it is called in Windows).

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 -m <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`_.


OPTIONS
-------

  -b   Exclude file/directory "extension" when doing string
       substitution.
       (*Default*: Substitute within the entire file/directory name)


  -e   Only do string substitutions in the filename "extension".
       (*Default*: Substitute within the entire file/directory name)


  -g   Replace all instances (greedy replace) of the old string 
       with the new.

  -h   Print help information.


  -l string   File "extension" delimiter string.
              (*Default*: ".")

  -m template   Rename by template. (*Default*: Rename via string replacement.)


  -q   Quiet mode, do not show progress.
       (*Default*: Display progress)


  -r <old=new>   Replace "oldstring" with "newstring" in filenames.


  -t   Test mode, don't rename, just show what the program *would* do
       (ignores -q).


  -v   Print detailed program version information and exit.

  -w   Turn off warnings about potentially overwriting existing
       files or directories.
       (*Default*: Warn if target exists.)

  -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)


TEMPLATE CONSTRUCTION
---------------------


EXAMPLES
--------


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.108 2010/01/15 18:47:47 tundra Exp $

You can find the latest version of this program at:

  http://www.tundraware.com/Software/tren