diff --git a/tren.rst b/tren.rst index 735040f..86ee970 100644 --- a/tren.rst +++ b/tren.rst @@ -116,12 +116,21 @@ This option is ignored when running in test mode (``-t``). - -r Replace "oldstring" with "newstring" in file names. + -r Replace ``old`` with ``new`` in file or directory + 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. + 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 in + which case ``old`` is treated as a Python style + regular expression. + + Both ``old`` and ``new`` may optionally contain + *Renaming Tokens* described later in this document. + + If you need to use the ``=`` symbol *within* either + the old or new string, simply escape it: ``\=`` + You can have multiple instances of this option on your **tren** command line:: @@ -134,14 +143,10 @@ 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. - If you need to use the ``=`` symbol *within* either - the old or new string, simply escape it: ``\=`` - - -t Test mode, don't rename, just show what the program *would* do (ignores -q). @@ -152,7 +157,6 @@ 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. -x Treat the old string in a ``-r`` replacement as a Python @@ -168,7 +172,7 @@ .. 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! + option) to see what would 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 @@ -328,13 +332,13 @@ 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:: +named and numbered files. You might start with 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) + 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: +It would be nice to get these in order somehow:: tren.py -r =/D/-MyVacation-/+T0001/.jpeg *.jp* @@ -346,9 +350,9 @@ 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) + 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 ``/+T0001/`` @@ -358,12 +362,16 @@ .. Note:: Notice that there is *no old string* in our example above. That is, there is nothing to the left of the ``=`` symbol in - the ``-r`` option. This effectively means "match anything" - in the existing file or directory name. You can do - the same thing using a regular expression:: + the ``-r`` option. This effectively means "replace + everything" in the existing file or directory name. You can + do the same thing using a regular expression:: tren.py -x -r *=/D/-MyVacation-/+T001/.jpeg *.jp* + Of course, if you use the ``-b`` or ``-e`` flags, you limit + just what portion of the filename is considered + "everything". + Of course, you don't *have* to replace the entire filename when using tokens. It's perfectly legitimate to replace only a portion of the existing name:: @@ -375,7 +383,7 @@ token to do this. You can even use renaming tokens in your *old string* specification. -For instance, suppose you manage a number of different systems that +For instance, suppose you manage a number of different systems and you set their system name in an environment variable called SYSNAME. You might then do something like this:: @@ -389,27 +397,25 @@ There are a couple of things to keep in mind when doing things like this: - 1) The ``/$SYSNAME/`` in the old string is used to *find the - text to rename*, whereas the same renaming token in the - new string means *insert the contents of that environment - variable here*. + 1) The ``/$SYSNAME/`` in the old string is used to *find the text to + rename*, whereas the same renaming token in the new string means + *insert the contents of that environment variable here*. 2) Renaming tokens are always evaluated *before* any regular - expression processing takes place. It's up to you to - make sure that when you combine the two (as we have in - the example above), *that the final result is still a - valid Python regular expression*. This may involve - explicit quoting of the renaming tokens used in the old - string specification. + expression processing takes place. It's up to you to make sure + that when the two are combined (as we have in the example above), + *that the final result is still a valid Python regular + expression*. This may involve explicit quoting of the renaming + tokens used in the old string specification. **tren** has many other kinds of renaming tokens. Their structure and use is described in some detail in the -section below entitled, `RENAMING TOKENS`_. +next section. -RENAMING TOKENS ---------------- +RENAMING TOKENS: THE GORY DETAILS +--------------------------------- Token based renaming is used when you want to impose a naming "pattern" on a group of files or directories. This is most useful @@ -588,10 +594,18 @@ Here are some common examples of **tren** in action - the resulting file name(s) shown to the right as a comment. Study each example -carefully. Small subtleties are introduced in various -adjacent examples to illustrate diffent features of **tren**: +carefully. Small subtleties are introduced in various adjacent +examples to illustrate different features of **tren**: + Get help:: + + tren.py -h + + Print out detailed version information:: + + tren.py -v + Simple rename:: tren.py -r old=New fold.txt log.old # fNew.txt log.New @@ -626,23 +640,15 @@ Use renaming token:: - tren.py -T /I/ file.1 # 2010-01-12 + tren.py -r =/I/ file.1 # 2010-01-12 Use renaming token to change file "name":: - tren.py -b -T /I/ file.1 file.2 # 2010-01-12.1 2010-01-12.2 + tren.py -b -r =/I/ file.1 file.2 # 2010-01-12.1 2010-01-12.2 Use renaming token to change file "extension":: - tren.py -e -T /D/ file.1 # file.20100112 - - Get help:: - - tren.py -h - - Print out detailed version information:: - - tren.py -v + tren.py -e -r =/D/ file.1 # file.20100112 OTHER @@ -683,7 +689,7 @@ :: - $Id: tren.rst,v 1.125 2010/01/20 00:26:22 tundra Exp $ + $Id: tren.rst,v 1.126 2010/01/20 16:20:39 tundra Exp $ You can find the latest version of this program at: