Fork: 0
tundra / tren
Browse code
Finished renaming token overview.
Expunged all old references to -T.
Put Help and Version at the top of the Examples list.
master
1 parent 614f9dd commit 44d507716ebecbd495f8550a8e22cc1d1ce58cd9
@tundra tundra authored on 20 Jan 2010
Patch
Unified Split
Showing 1 changed file
View
147
■■■■■
 tren.rst
 
This option is ignored when running in test mode (``-t``).
 
 
-r <old=new> 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.
-r <old=new> 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 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::
 
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.
 
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).
 
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.
 
-x Treat the old string in a ``-r`` replacement as a Python
style regular expression for matching purposes.
 
.. 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
renaming *batches* of files and/or directories with a single command
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:
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
 
It would be nice to get these in order somehow::
 
tren.py -r =/D/-MyVacation-/+T0001/.jpeg *.jp*
 
This would rename all the files in the current directory ending with
``-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)
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/``
renaming token in our pattern. The ``+`` here means to construct
*descending* order.
 
.. 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::
20100101-file.2`` Notice that we combined literal text and a renaming
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::
 
tren.py -x -r /$SYSNAME/*.bku=/$SYSNAME/*.bku.old
 
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`_.
 
 
RENAMING TOKENS
---------------
next section.
 
 
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
when the existing filenames have little or nothing in common. In such
--------
 
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
tren.py -r a\=b=c\=d a=b.txt # c=d.txt
 
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
-----
-----------------------------
 
::
 
$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:
 
http://www.tundraware.com/Software/tren