Added .py suffix to all tren command invocation examples. Added text explaining why destructive renames are not permitted. Removed -w option and references to destructive overwrites.

Fork: 0

tundra / tren

Browse code Added .py suffix to all tren command invocation examples. Added text explaining why destructive renames are not permitted. Removed -w option and references to destructive overwrites. master
1 parent e28e065 commit 942b0593f004a0086723cbd51a34601b0f5ba5b6 tundra authored on 15 Jan 2010

Patch

Unified Split

Showing 1 changed file

                Ignore Space
               Show notes
              View
            
          
          65 ■■■■■
          tren.rst
 --------
 
::
 
    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
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** 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*.
 
 
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
  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
such a substitution takes place *anywhere* in the file name, not just at
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*
  tren.py -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
      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
        tren.py -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
        tren.py -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
         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
       is preserved.
       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
          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.
 
       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
         tren.py -g -r p:P pop.txp    # Renames file to: PoP.txP
 
  -h   Print help information.
 
 
              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
                tren.py -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
 
                 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::
 
                   new-old.doc
       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)
      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
        tren.py -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.    
 
-----------------------------
 
::
 
  $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:
 
  http://www.tundraware.com/Software/tren
 --------
 ::
+    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
 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** 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*.
 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
+  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
 such a substitution takes place *anywhere* in the file name, not just at
 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*
+  tren.py -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
       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
+        tren.py -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
+        tren.py -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
+         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
        is preserved.
        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
+          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.
        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
+         tren.py -g -r p:P pop.txp    # Renames file to: PoP.txP
   -h   Print help information.
               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
+                tren.py -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
                  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::
                    new-old.doc
        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)
       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
+        tren.py -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.
 -----------------------------
 ::
+  $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:
   http://www.tundraware.com/Software/tren

Show line notes below