NAME

tren - Advanced File Renaming

SYNOPSIS

tren.py [-cbeghqtvwx] [-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 file name, 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)

Many applications use the suffix of a filename to indicate the contents or type of file. By default, tren does string substiution in the entire filename including the extension. For example doing this:
tren -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 -b -r eg=ug   peg.jpeg   # Renames file to pug.jpeg
-c
Collapse case when doing string substitution.

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 -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 do string substitutions in the filename "extension". (Default: Substitute within the entire file/directory name)

This option is the inverse of -b. It instructs tren to do the requested subsitution only in the filename "extension" not on the file name portion. For example:
tren -e -r pe=p   peg.jpeg   # Renames file to peg.jpg
-g
Replace all instances (greedy replace) of the old string with the new.

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

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

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

By default, tren warns you if you're about to rename a file/directory with a name of a file/directory that already exists. No renaming takes place in that case. You can suppress this behavior with the -w option. In that case tren will attempt to do the renaming without warning you. If it cannot - for example, if your proposed renaming would remove a non-empty directory - tron will print a message to that effect even with this option selected.
-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 -x -r bb+:X *.txt
This renames the files to:
sXs-1.txt
sXs-2.txt
sXs-3.txt

Be VERY Careful with this option.  It's very easy to write
regular expressions that collapse all existing file names to a
single new name.  If you do this with the ``-w`` option
selected, you're likely going to end up clobbering files you
never meant to.

**tren** only accepts Python style regular expressions.  Anything
else will cause an error message to be displayed.

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

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.110 2010/01/15 20:55:25 tundra Exp $

You can find the latest version of this program at:

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