diff --git a/tren.rst b/tren.rst index a294293..4f390c6 100644 --- a/tren.rst +++ b/tren.rst @@ -8,19 +8,16 @@ :: - tren.py [-cbeghqtvwx] [-l string] [-m template] [-r old=new]... file|dir file|dir ... + tren.py [-cbeghqtvx] [-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! +.. WARNING:: **tren** is a powerful file and directory renaming tool. + 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 @@ -28,6 +25,13 @@ line invocation. **tren** eliminates the tedium of having to script simpler tools to provide higher-level renaming capabilities. +**tren** will not allow you to rename a file/directory if a +file/directory with the new name already exists. Such attempts will +cause no change to the file/directory being processed and a warning +message will be displayed. This is intentional to force you to +manually rename or remove the directory that would have been clobbered +by a rename. + **tren** supports two kinds of renaming operations, *String Substitution* and *Rename By Template*. @@ -39,7 +43,7 @@ that have a common set of characters in them you'd like to change. For instance:: - tren -r .Jpeg=.jpg *.Jpeg + tren.py -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 @@ -88,7 +92,7 @@ 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* + tren.py -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 @@ -123,7 +127,7 @@ substiution in the entire filename *including* the extension. For example doing this:: - tren -r eg=ug peg.jpeg + tren.py -r eg=ug peg.jpeg Renames the file to ``pug.jpug`` .. probably not what you want. @@ -131,7 +135,7 @@ 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 + tren.py -b -r eg=ug peg.jpeg # Renames file to pug.jpeg -c Collapse case when doing string substitution. @@ -139,7 +143,7 @@ **tren** will ignore the case of the characters found in the filename. For example:: - tren -c -r Old:NEW Cold.txt fOlD.txt + tren.py -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 @@ -152,7 +156,7 @@ 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 + tren.py -e -r pe=p peg.jpeg # Renames file to peg.jpg -g Replace all instances (greedy replace) of the old string with the new. @@ -163,7 +167,7 @@ *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 + tren.py -g -r p:P pop.txp # Renames file to: PoP.txP -h Print help information. @@ -178,7 +182,7 @@ 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 + tren.py -b -l .long.txt -r long:short long.long.txt.long.txt.foo This would rename the file to:: @@ -217,7 +221,7 @@ You can have multiple instances of this option on your **tren** command line:: - tren -e old:new -e txt:doc old-old.txt + tren.py -e old:new -e txt:doc old-old.txt This renames the file to:: @@ -243,20 +247,6 @@ -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) @@ -280,7 +270,7 @@ a *Python style regular expression*. That way, a single string can be used to match many cases:: - tren -x -r bb+:X *.txt + tren.py -x -r bb+:X *.txt This renames the files to:: @@ -288,12 +278,6 @@ 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. @@ -340,7 +324,7 @@ :: - $Id: tren.rst,v 1.111 2010/01/15 20:57:07 tundra Exp $ + $Id: tren.rst,v 1.112 2010/01/16 00:04:27 tundra Exp $ You can find the latest version of this program at: