NAME
----

**tren** - Advanced File Renaming

SYNOPSIS
--------

::

    tren.py [-bdehipqtvwx] [-l string] [-r old=new]... [-s number] 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** supports two kinds of renaming operations, String Substitution
and Rename By Date.


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 files.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 Date
--------------



OPTIONS
-------

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


  -d   Rename by date sequence. (Default: Rename via string replacement.)

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


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

  -h   Print help information.


  -i   Use ISO date format when renaming by date sequence.
       (Default: "YYYYMMDD")


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


  -p   Prepend, do not replace, file name with date sequence.
       (Default: Replace filename)


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


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


  -s number   Set starting sequence number when renaming by date.
              (Default: 0)

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


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.106 2010/01/15 02:39:41 tundra Exp $

You can find the latest version of this program at:

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