NAME

tren - Advanced File Renaming

SYNOPSIS

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

DESCRIPTION

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