diff --git a/tren.rst b/tren.rst index 2c52c29..6dca419 100644 --- a/tren.rst +++ b/tren.rst @@ -8,7 +8,7 @@ :: - tren.py [-bdehipqtvwx] [-l string] [-r old=new]... [-s number] file|dir file|dir ... + tren.py [-beghqtvwx] [-l string] [-m template] [-r old=new]... file|dir file|dir ... DESCRIPTION @@ -25,10 +25,11 @@ **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. +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 Date. +**tren** supports two kinds of renaming operations, *String Substitution* +and *Rename By Template*. String Substition @@ -38,7 +39,7 @@ that have a common set of characters in them you'd like to change. For instance:: - tren -r .Jpeg=.jpg files.Jpeg + 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 @@ -60,9 +61,54 @@ but not idential strings in their names you'd like to replace. -Rename By Date --------------- +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 -MyVacation-<0001>.jpeg *.jp* + +This would rename all the files in the current directory ending with +``.jp*``. The ```` 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 @@ -73,8 +119,6 @@ (*Default*: Substitute within 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 within the entire file/directory name) @@ -85,16 +129,10 @@ -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) + -m template Rename by template. (*Default*: Rename via string replacement.) -q Quiet mode, do not show progress. @@ -104,9 +142,6 @@ -r 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). @@ -122,6 +157,10 @@ (*Default*: Treat the old string as literal text) +TEMPLATE CONSTRUCTION +--------------------- + + EXAMPLES -------- @@ -160,7 +199,7 @@ :: - $Id: tren.rst,v 1.107 2010/01/15 02:42:36 tundra Exp $ + $Id: tren.rst,v 1.108 2010/01/15 18:47:47 tundra Exp $ You can find the latest version of this program at: