Fork: 0
tundra / tren
Browse code
More edits of command line options reference material.
master
1 parent 22c566a commit ac7fd3f377d5a90b99652285a8e6c1f4ab7f7c96
@tundra tundra authored on 19 Mar 2010
Patch
Unified Split
Showing 1 changed file
View
385
■■■■■
 tren.rst
 
.. WARNING:: **tren** is very powerful and can easily and
automatically rename things in ways you didn't intend.
It is ***strongly*** recommended that you try out new
**tren** operations with the ``-t`` option on the command
**tren** operations with the '``-t``' option on the command
line. This turns on the "test mode" and will show you
what the program *would* do without actually doing it.
It goes without saying that you should be even more
careful when using this program as the system root or
 
You may specify *tren* options in one of three ways:
 
1) On the command line
2) In an "include" file specified with ``-I filename`` on the command line
2) In an "include" file specified with '``-I filename``' on the command line
3) Via the ``$TREN`` environment variable
 
Options specified on the command line are evaluated from left to right
and supercede any options specified in the environment variable.
Think of any options set in ``$TREN`` as the "leftmost command line
options".
 
All options must precede the list of files and/or directories being
renamed. If one of your rename targets start with the ``-`` character,
renamed. If one of your rename targets start with the '``-``' character,
most command shells recognines the double dash as an explicit
"end of options" delimiter::
 
tren.py -opt -opt -opt -- -this_file_starts_with_a_dash
program permanently and cannot be undone by subsequent options. Some
options are "toggles", they can be turned on- and off as you move from
left- to right on the command line. In this way, certain options
(like case sensitivity, regular expression handling, and so on) can be
set differently for each individual renaming request (``-r``). (If
you're very brave, you can select the ``-d`` option to do a debug
set differently for each individual renaming request ('``-r``'). (If
you're very brave, you can select the '``-d``' option to do a debug
dump. Among many other things, the **tren** debugger dumps the state
of each renaming request, and what options are in effect for that
request.)
 
 
(*Default*: off)
 
This option is provided so you can toggle the program back to
its default behavior after a previous ``-b`` or ``-e`` on the
its default behavior after a previous '``-b``' or '``-e``' on the
command line.
 
-C Do case-sensitive renaming
 
(*Default*: This is the program default)
 
This option is provided so you can toggle the program back to
its default behavior after a previous ``-c`` on the command
its default behavior after a previous '``-c``' on the command
line.
 
This option is observed both for literal and regular
expression-based renaming (``-x``). .
expression-based renaming ('``-x``'). .
 
-c Collapse case when doing string substitution.
 
(*Default*: Search for string to replace is case sensitive)
respectively. Notice that the new (replacement) string's case
is preserved.
 
This option is observed both for literal and regular
expression-based renaming (``-x``).
expression-based renaming ('``-x``').
 
 
-d Dump debugging information
 
is already in use by another file or directory. This option
forces the renaming to take place. However, the old file or
directory is not lost. It is merely renamed itself first, by
appending a suffix to the original file name. (*Default*:
.backup, but you can change it via the ``-S`` option.) This
.backup, but you can change it via the '``-S``' option.) This
way even forced renames don't clobber existing files or
directories.
 
-h Print help information.
 
-I file "Include" command line arguments from ``file``
 
It is possible to perform multiple renaming operations in one
step using more than one ``-r`` option on the **tren** command
step using more than one '``-r``' option on the **tren** command
line. However, this can make the command line very long and
hard to read. This is especially true if the renaming strings
are complex, contain regular expressions or renaming
tokens, or if you make heavy use of command line toggles.
 
The ``-I`` option allows you to place any command line
The '``-I``' option allows you to place any command line
arguments in a separate *file* in place of- or in addition to
the **tren** command line and/or the ``$TREN`` environment
variable. This file is read one line at a time and the
contents appended to any existing command line. You can even
To avoid this, **tren** limits the total number of inclusions
to 1000. If you exceed this, you'll get an error message and
the program will terminate.
 
.. NOTE:: Wilcard metacharcters like ``*`` and ``?`` that are
embedded in filenames included this way *are* expanded as
they would be from the command shell.
 
-i num|range Specifies which "instances" of matching strings should
be replaced. (*Default*: 0 or leftmost)
 
An existing file may have multiple instances of the
"old" renaming string in it. The ``-i`` option lets
you specify which of these (one, several, all) you'd
like to have replaced.
 
Suppose you have a file called
``foo1-foo2-foo3.foo4``. The leftmost ``foo`` is
instance 0. The rightmost ``foo`` is instance 3.
You can also refer to instances relative to the
right. So the -1 instance is the last (rightmost),
-2, second from the last, and so forth.
 
A "range" of instances is specified
using the ``:`` separator in the form::
 
-i first-to-replace:stop-here
 
All instances from the first-to-replace
up to, *but NOT including* the stop-here
are replaced. ``-i :`` means "replace
*all* instances.
 
Examples::
 
tren.py -i 1 -r foo=bar foo1-foo2-foo3.foo4 -> foo1-bar2-foo3.foo4
tren.py -i -1 -r foo=bar foo1-foo2-foo3.foo4 -> foo1-foo2-foo3.bar4
tren.py -i 1:3 -r foo=bar foo1-foo2-foo3.foo4 -> foo1-bar2-bar3.foo4
tren.py -i -4:-2 -r foo=bar foo1-foo2-foo3.foo4 -> bar1-bar2-foo3.foo4
tren.py -i : -r foo=bar foo1-foo2-foo3.foo4 -> bar-bar2-foo3.bar4
Note that wildcard metacharacters like ``*`` and ``?`` that are
embedded in filenames included this way are expanded as they
would be from the command shell.
 
-i instances Specifies which "instances" of matching strings should
be replaced.
(*Default*: 0 or leftmost)
 
A file may have multiple instances of the "old"
renaming string in it. The '``-i``' option lets you
specify which of these (one, several, all) you'd
like to have replaced.
 
Suppose you have a file called
'``foo1-foo2-foo3.foo4``'. The leftmost ``foo`` is
instance 0. The rightmost '``foo``' is instance 3.
You can also refer to instances relative to the
right. So the -1 instance is the last (rightmost),
-2, second from the last, and so forth.
 
A "range" of instances is specified
using the '``:``' separator in the form::
 
-i first-to-replace:stop-here
 
All instances from the "first-to-replace"
up to, *but NOT including* "the stop-here"
are replaced. '``-i :``' means "replace
*all* instances.
 
Examples::
 
tren.py -i 1 -r f=b foo1-foo2-foo3.foo4
-> foo1-boo2-foo3.foo4
 
tren.py -i -1 -r f=b foo1-foo2-foo3.foo4
-> foo1-foo2-foo3.boo4
 
tren.py -i 1:3 -r f=b foo1-foo2-foo3.foo4
-> foo1-boo2-boo3.foo4
 
tren.py -i -4:-2 -r f=b foo1-foo2-foo3.foo4
-> boo1-boo2-foo3.foo4
 
tren.py -i : -r f=b foo1-foo2-foo3.foo4
-> boo1-boo2-boo3.boo4
-P char Use '``char``' as the escape symbol.
(*Default*: '``\``')
 
-q Quiet mode, do not show progress.
 
(*Default*: Display progress)
 
Ordinarily, **tren** displays what it is doing as it
processes each file. If you prefer to not see this
"noisy" output, use the ``-q`` option. Note that this
"noisy" output, use the '``-q``' option. Note that this
does not suppress warning and error messages.
 
This option is ignored when running in test mode (``-t``).
 
 
-r <old=new> Replace ``old`` with ``new`` in file or directory
 
-R char Use '``char``' as the separator symbol in renaming
specifications.
(*Default*: '``=``')
 
-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
literally unless you also invoke the '``-x``' option. In
that case, '``old``' is treated as a Python style
regular expression.
 
Both ``old`` and ``new`` may optionally contain
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: ``\=``
 
If you need to use the '``=``' symbol *within* either
the old or new string, simply escape it: '``\=``'
 
If it is convenient, you can change the separator
character to something other than '``=``' via the
'``-R``' option. Similarly, you can change the
escape character via the '``-P`` option.
 
You can have multiple instances of this option on
your **tren** command line::
 
tren.py -e old:new -e txt:doc old-old.txt
tren.py -r old:new -r txt:doc old-old.txt
 
This renames the file to::
 
new-old.doc
By default, **tren** only replaces the first
Remember that, by default, **tren** only replaces the first
(leftmost) instance of the old string with the new.
 
Each rename specifiation on the command line "remembers"
the current state of all the program options and acts
accordingly. For example::
 
tren.py -cr A=bb -Cr B=cc ...
 
The '``A=bb``' replacement would be done without
regard to case (both '``A``' and '``a``' would match),
where as the '``B=cc``' request would only replace
'``B``'.
 
-t Test mode, don't rename, just show what the program *would* do
(ignores -q).
 
 
(*Default*: This is the program default)
 
This option is provided so you can toggle the program back to
its default behavior after a previous ``-x`` on the command
its default behavior after a previous '``-x``' on the command
line.
 
-x Treat the old string in a ``-r`` replacement as a Python
-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)
 
------------------------
 
.. 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``
not, run the program in test mode (invoke with the '``-t``'
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
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.
 
file or directory being processed and an error message will be
displayed. This is intentional to force you to manually rename or
remove the file or directory that would have been clobbered by a
rename. You can override this default and *force* a renaming and thus
the removal of such existing files or directories (``-f`` option).
the removal of such existing files or directories ('``-f``' option).
 
**tren** supports a variety of renaming mechanisms. The one thing
they have in common is that you must specify an *old string* which
will be replaced by a *new string* when the file or directory is
 
tren.py -r old=new <list of files, directories to rename>
 
 
The ``old`` and ``new`` renaming strings are built using a variety of
The '``old``' and '``new``' renaming strings are built using a variety of
building blocks:
 
============================= =============================
*Old Strings Are Built With:* *New Strings Are Built With:*
 
tren.py -r .Jpeg=.jpg *.Jpeg
 
This would rename all files (or directories) whose names contained the
string ``.Jpeg`` and replace it with ``.jpg``. Well ... that's not
quite right. Unless you specify the ``-g`` option, *only the first
(leftmost) instance of ``old`` is replaced with ``new``*.
string '``.Jpeg``' and replace it with '``.jpg``'. Well ... that's not
quite right. Unless you specify the '``-g``' option, *only the first
(leftmost) instance of '``old``' is replaced with '``new``'*.
 
It's important to realize that such a substitution takes place
*anywhere* in the file name, not just at the end or "extension" (as it
is called in Windows). You can limit the replacement to just the
"name" (``-b``) or "extension" (``-e``) portions of the filename.
 
You may specify multiple replacement operations (``-r``) on the **tren**
"name" ('``-b``') or "extension" ('``-e``') portions of the filename.
 
You may specify multiple replacement operations ('``-r``') on the **tren**
command line::
 
tren.py -g -r .Jpeg=.jpg -r old=ReallyOld *
 
This would rename all the files in the current directory, replacing
``.Jpeg`` with ``.jpg`` and ``old`` with ``ReallyOld`` anywhere these
'``.Jpeg``' with '``.jpg``' and '``old``' with '``ReallyOld``' anywhere these
strings appeared in any of the file or directory names.
 
If you need to include the equals sign as part of the old string or
the new string literal text, you have to escape it (``\=``)::
the new string literal text, you have to escape it ('``\=``')::
 
tren.py -r name\=bob=name\=sally name=bob.dbms
 
This renames the file ``name=bob.dbms`` to ``name=sally.dbms``.
This renames the file '``name=bob.dbms``' to '``name=sally.dbms``'.
 
 
Using Regular Expressions
-------------------------
 
Ordinarily **tren** treats both the old string you specify with the
``-r`` option *literally*. However, it is sometimes handy to be able
'``-r``' option *literally*. However, it is sometimes handy to be able
to write a regular expression to specify what you want replaced. If
you specify the ``-x`` option, **tren** will treat your old string as
you specify the '``-x``' option, **tren** will treat your old string as
a Python style regex, compile it (or try to anyway!) and use it to
select which strings to replace. This makes it much easier to rename
files that have repeated characters or patterns, and groups of files
that have similar, but not idential strings in their names you'd like
sbbbs-2.txt
sbbbbbbbbs-3.txt
 
Suppose you want to rename them, replacing two or more instances of
``b`` with ``X``. It is tedious to have to write a separate literal
``-r old:new`` string substitution for each instance above. This is
'``b``' with '``X``'. It is tedious to have to write a separate literal
'``-r old:new``' string substitution for each instance above. This is
where regular expressions can come in handy. When you invoke the
``-x`` option, **tren** understands this to mean that the ``old``
'``-x``' option, **tren** understands this to mean that 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::
sXs-2.txt
sXs-3.txt
 
Keep in mind that a literal string is a subset of a regular
expression. This effectively means that with ``-x`` processing
expression. This effectively means that with '``-x``' processing
enabled you can include *both* regular expressions and literal text in
your "old string" specification. The only requirement is that the
string taken as a whole must be a valid Python regular expression. If
it is not, **tren** will display an error message to that effect.
 
Because Python regular expressions can make use of the ``=`` symbol,
you need a way to distinguish between an ``=`` used in a regular
Because Python regular expressions can make use of the '``=``' symbol,
you need a way to distinguish between an '``=``' used in a regular
exression and the same symbol used to separate the old and new
operands for the ``-r`` option. Where this symbol needs to appear in
a regular expression, it has to be escaped like this: ``\=``.
 
Regular expression processing is unaffected by the ``-g / -1`` (global
rename) and ``-c / -C`` (ignore case) options. That's because there
operands for the '``-r``' option. Where this symbol needs to appear in
a regular expression, it has to be escaped like this: '``\=``'.
 
Regular expression processing is unaffected by the '``-g / -1``' (global
rename) and '``-c / -C``' (ignore case) options. That's because there
are regular expression mechanisms for achieving the same thing. More
importantly, if you've selected regular expression matching, it's
probably because you want very fine grained control of the renaming
defined by the regex. In short, regular expression matching always
An Overview Of Renaming Tokens
------------------------------
 
**tren** implements the notion of *Renaming Tokens*. These can
appear in either the ``old`` or ``new`` string components of a ``-r``
appear in either the '``old``' or '``new``' string components of a '``-r``'
renaming argument.
 
It is sometimes useful to be able to take a group of files or
directories whose names have nothing in common and impose a common
its creation date, size, owner's name, and so on.
 
In their simplest form, renaming tokens are nothing more than
"canned" information **tren** knows about a particular file or
directory. For instance, if you insert the ``/D/`` token into a
directory. For instance, if you insert the '``/D/``' token into a
old- or new string definition, **tren** will replace it with *the
creation date of the file or directory being renamed* and use that
string in the renaming process.
 
 
tren.py -r =/D/-MyVacation-/+T0001/.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 ``/+T0001/`` refers to a *starting sequence number* to
'``.jp*``'. The '``/D/``' would be replaced with the *date* the picture
was taken. The '``/+T0001/``' refers to a *starting sequence number* to
uniquely identify pictures taken on the same date. The other strings,
``-MyVacation-`` and ``.jpeg``, are inserted *literally* in the final
'``-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 ``/+T0001/``
renaming token in our pattern. The ``+`` here means to construct
the sequence in *ascending* order. A ``-`` would specify
the time-of-day they were taken because we included the '``/+T0001/``'
renaming token in our pattern. The '``+``' here means to construct
the sequence in *ascending* order. A '``-``' would specify
*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 "replace
That is, there is nothing to the left of the '``=``' symbol in
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
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
a portion of the existing name::
 
tren.py -r file=/D/-file file-1 file.2
 
This would rename our files to: ``20100101-file-1 and
20100101-file.2`` Notice that we combined literal text and a renaming
This would rename our files to: '``20100101-file-1 and
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 and you
 
tren.py -x -r /$SYSNAME/*.bku=/$SYSNAME/*.bku.old
 
If your system name was "matrix", then the command above would only
rename files whose names began with ``matrix`` and ended with ``.bku``.
rename files whose names began with '``matrix``' and ended with '``.bku``'.
If your system name were "morton", then the command above would only
rename files whose names began with ``morton`` and ended with ``.bku``.
rename files whose names began with '``morton``' and ended with '``.bku``'.
 
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
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
--------------------
 
**tren** defaults to a specific set of behaviors:
 
- ``old`` and ``new`` renaming text is treated *literally*
- '``old``' and '``new``' renaming text is treated *literally*
- Renaming takes place within *the entire filename*
- *Only the first instance* of ``old`` is replaced with ``new``
- *Only the first instance* of '``old``' is replaced with '``new``'
- Renaming is *case sensitive*
 
There are command line "switches" to override each of these defaults
(``-x``, ``-b``, ``-e``, ``-g``, and ``-c``).
('``-x``', '``-b``', '``-e``', '``-g``', and '``-c``').
 
There are additional "switches" to return the program to its
default behavior (``-X``, ``-a``, ``-1``, and ``-C``).
default behavior ('``-X``', '``-a``', '``-1``', and '``-C``').
 
The idea is that you can specify what kind of replacement
behavior you want *for each different renaming operation*.
For instance::
tren.py -e -r txt=TXT -g -a -c -r M=0 -C -x -r [ss]+=S filelist
 
This would rename the files as follows:
 
- The first instance of ``txt`` would be replaced with
``TXT`` in each of the file extensions.
 
- All instances of ``m`` or ``M`` would be replaced
- The first instance of '``txt``' would be replaced with
'``TXT``' in each of the file extensions.
 
- All instances of '``m``' or '``M``' would be replaced
anywhere they were found in the filename.
 
- All instances of one or more strings in the form ``ss`` would
be replaced with ``S``.
- All instances of one or more strings in the form '``ss``' would
be replaced with '``S``'.
 
 
OTHER PROGRAM SEMANTICS
-----------------------
- Command line processing is from left to right. As we saw in the
`COMMAND LINE TOGGLES`_ above, this means the options can be
different for each renaming operating you specify.
 
- Regular expression processing is unaffected by the ``-g / -1``
(global rename) and ``-c / -C`` (ignore case) options.
- Regular expression processing is unaffected by the '``-g / -1``'
(global rename) and '``-c / -C``' (ignore case) options.
 
- Filenames may be absolute, relative, or implict (to the current
working directory). **tren** keeps track of this and can do
renaming in directories other than the current one.
1) Select the target portion of the filename for
renaming (all, name only, extension only).
 
2) Replace all renaming tokens with their equivalent
text in both the ``old`` and ``new`` renaming strings.
text in both the '``old``' and '``new``' renaming strings.
 
3) If doing literal string replacement:
 
- If ``-c`` is in effect, collapse the target and the ``old``
- If '``-c``' is in effect, collapse the target and the '``old``'
renaming string to *lower case* before checking for a match.
 
- Replace the first- (default and ``-1``) or all (``-g``)
instances of ``old`` with ``new``. 4)
- Replace the first- (default and '``-1``') or all ('``-g``')
instances of '``old``' with '``new``'. 4)
 
4) If doing regular expression processing, replace any regex
matches with the corresponding ``new`` string. Keep in mind
that if ``-x`` is selected the *entire* ``old`` string is
matches with the corresponding '``new``' string. Keep in mind
that if '``-x``' is selected the *entire* '``old``' string is
treated as a Python regular expression. Pay particular
attention to this if you're combing literal text and/or
renaming tokens with regular expression metacharacters.
 
- When all the renaming operations are complete - and thus a new filename
has been constructed - **tren** checks to see if a file or directory
by that name already exists. Unless the ``-f`` flag is in force,
by that name already exists. Unless the '``-f``' flag is in force,
**tren** will refuse to do a renaming *over an existing filename*.
If the new filename does not exist, **tren** will attempt the
renaming. If the rename fails for some reason - say you don't
have permission to rename a particular file or directory - you'll
see an error message to that effect.
 
- By default, **tren** will stop processing on any error. You
can override this with the ``-E`` option. In that case,
can override this with the '``-E``' option. In that case,
an error message will be displayed. No matter what caused
the error, **tren** will skip the file currently being processed
and go on to the next one.
 
- An attribute of the file or directory being renamed
- An attribute of the underling operating system environment
- A sequence that reflects some ordering principle
 
Renaming tokens are delimited by the ``/`` character. **tren**
Renaming tokens are delimited by the '``/``' character. **tren**
replaces these tokens with the corresponding information (see
descriptions below) wherever you indicated in either the ``old`` or
``new`` strings of a ``-r`` rename command.
descriptions below) wherever you indicated in either the '``old``' or
'``new``' strings of a '``-r``' rename command.
 
Currently, **tren** defines a number of renaming tokens. Future
releases of **tren** may add more of these, so it's good to
periodically reread this material.
``/D/ File or directory creation date``
 
This token is replaced with the date of creation
of the file or directory being renamed. It is
in ``yyyymmdd`` format.
in '``yyyymmdd``' format.
 
``/dd/ File or directory day of creation``
 
This token is replaced with the the day of the month the
file was created in ``dd`` format.
file was created in '``dd``' format.
 
``/dy/ File or directory day of creation``
 
This token is replaced with the the name of the day the
file was created in ``Ddd`` format.
file was created in '``Ddd``' format.
 
``/E/ Original File Extension``
 
This token is replaced the "extension" portion of the file
This token is replaced the "name" portion of the file or
directory before renaming.
 
.. NOTE:: Notice that there is no token for the *whole* filename
because you can always synthesize it with ``/F/./E/``
because you can always synthesize it with '``/F/./E/``'
 
 
``/G/ File or directory primary group name``
 
 
``/hh/ File or directory hour of creation``
 
This token is replaced with the hour the file was
created in ``hh`` format.
created in '``hh``' format.
 
``/I/ File or directory creation date in ISO format``
 
This token is replaced with the date of creation of the
file or directory being renamed. It is similar to ``/D/``
except it is in ISO format, ``YYYY-MM-DD``.
file or directory being renamed. It is similar to '``/D/``'
except it is in ISO format, '``YYYY-MM-DD``'.
 
``/L/ File or directory length``
 
This token is replaced with a numeric string
 
``/mm/ File or directory minutes of creation``
 
This token is replaced with the minutes the file was
created in ``mm`` format.
created in '``mm``' format.
 
``/mo/ File or directory month of creation``
 
This token is replaced with the numeric month the file was
created in ``mm`` format.
created in '``mm``' format.
 
``/my/ File or directory month of creation``
 
This token is replaced with the abbreviated name of the
month the file was created in ``Mmm`` format.
month the file was created in '``Mmm``' format.
 
``/ss/ File or directory seconds of creation``
 
This token is replaced with the seconds the file was
created in ``ss`` format.
created in '``ss``' format.
 
``/T/ File or directory creation time``
 
This token is replaced with the time of creation of the
file or directory being renamed. It is in ``hh:mm:ss``
format. This is equivalent to ``/hh/:/mm/:/ss/``.
file or directory being renamed. It is in '``hh:mm:ss``'
format. This is equivalent to '``/hh/:/mm/:/ss/``'.
 
``/U/ File or directory owner name``
 
This token is replaced with the name of the
 
``/yyyy/ File or directory year of creation``
 
This token is replaced with the year the file was
created in ``yyyy`` format.
created in '``yyyy``' format.
 
 
 
 
 
``/$ENV/ Environment variable``
 
This token is replaced with the value of
the environment variable ``$ENV``. If
the environment variable '``$ENV``'. If
that variable does not exist, the token
is replaced with an empty string::
 
tren.py -r =/$ORGANZATION/-/F/./E/ *
 
``/`cmd`/ Arbitrary command execution``
 
This token is replaced with the string
returned by executing the ``cmd`` command.
returned by executing the '``cmd``' command.
 
For instance, you might want to prepend the name
of the system to a all you shell scripts::
 
---------------------------
 
Sometimes it's useful to rename files or directories based on some
*property they possess* like the date or time of creation, the size of
the file, who owns it, and so on. That's the idea behind the ``/D/``,
``/L/``, and ``/T/`` renaming tokens described in the previous section.
the file, who owns it, and so on. That's the idea behind the '``/D/``',
'``/L/``', and '``/T/``' renaming tokens described in the previous section.
 
An extension of this idea is to *order all the files being renamed*
based on one of these parameters. For instance, instead of actually
embedding the date and time of creation in a file or directory name,
0001 -> 0001, 0002, 0003, ...
0000 -> 0000, 0001, 0002, ...
03 -> 03, 04, 05, ...
 
You do not have to use a ``0`` to indicate the sequence width. You
You do not have to use a '``0``' to indicate the sequence width. You
can use *any* padding characters you like. **tren** only cares about
the width of the field and will "consume" your padding characters as
the count increases.::
 
 
``tren.py -b -r =/+D0002/ *.txt``
 
This would rename all the files in the current
directory into the form, ``0002.txt``, ``0003.txt``,
... ``9999.txt`` with ``0002.txt`` being the oldest
file and ``9999.txt`` being the newest. If you
used the token ``/-D0002/``, you'd get the same
directory into the form, '``0002.txt``', '``0003.txt``',
... '``9999.txt``' with '``0002.txt``' being the oldest
file and '``9999.txt``' being the newest. If you
used the token '``/-D0002/``', you'd get the same
thing, but in reverse order.
 
``/+L0001/ Sequence based on the size of the files being renamed``
 
 
``tren.py -r /+L0002/ *.txt``
 
This would rename all the files in the current
directory into the form, ``0002.txt``, ``0003.txt``,
... ``9999.txt`` with ``0002.txt`` being the shortest
file and ``9999.txt`` being the longest. If you
used the token ``/-L0002/``, you'd get the same
directory into the form, '``0002.txt``', '``0003.txt``',
... '``9999.txt``' with '``0002.txt``' being the shortest
file and '``9999.txt``' being the longest. If you
used the token '``/-L0002/``', you'd get the same
thing, but in reverse order.
 
``/+R0001/ Sequence based on the file order on the command line``
 
on the command line.
 
``tren.py -e -r =/+R0000/ MyFile.txt AFile.jpg me.log``
 
This would rename all the files to, ``MyFile.0``,
``AFile.1``, and ``me.2``. If you used ``/-R0000/``,
you'd get ``MyFile.2``, ``AFile.1```, and ``me.0``.
This would rename all the files to, '``MyFile.0``',
'``AFile.1``', and '``me.2``'. If you used '``/-R0000/``',
you'd get '``MyFile.2``', '``AFile.1``'`, and '``me.0``'.
 
``/+T0001/ Sequence based on creation time within date``
 
This produces a sequence based on the creation date
and time similar to the ``/+D.../`` sequence renaming
and time similar to the '``/+D.../``' sequence renaming
token above. However, the sequence *resets* at the
beginning of each new date. This allows you to
create unique sequences *within a date* like our
example of renaming photo files from different
tren.py -b -r =/D/-/+T0100/ *.txt
 
This would rename all the ``.txt`` files in the current
This would rename all the '``.txt``' files in the current
directory into the form::
 
200103010-0100.txt
200103010-0101.txt
...
 
In other words, instead of sequence just on the creation date,
this allows us to sequence *within* the date. As always, the
``-`` flag will reverse this order within the date.
'``-``' flag will reverse this order within the date.
 
Notice that you can get something similar using just
file attribute renaming tokens::
 
Rename using regular expressions::
 
tren.py -x -r a+=a Saaaaaaaally.doc # Sally.doc
 
Rename a file containing the ``=`` symbol::
Rename a file containing the '``=``' symbol::
 
tren.py -r a\=b=c\=d a=b.txt # c=d.txt
 
Use renaming token::
 
As a general matter, **tren** should run on any POSIX-compliant OS
that has this version (or later) of Python on it. It will also run on
many Microsoft Windows systems. If the Windows system has the
``win32all`` Python extensions installed, **tren** will take advantage
'``win32all``' Python extensions installed, **tren** will take advantage
of them for purposes of deriving the names of the user and group that
own the file or directory being renamed.
 
As of this writing, **tren** will not run in the **cygwin** environment
-----------------------
 
**tren** is Copyright (c) 2010 TundraWare Inc.
 
For terms of use, see the ``tren-license.txt`` file in the
For terms of use, see the '``tren-license.txt``' file in the
program distribution. If you install **tren** on a FreeBSD
system using the 'ports' mechanism, you will also find this file in
``/usr/local/share/doc/tren``.
'``/usr/local/share/doc/tren``'.
 
 
AUTHOR
------
-----------------------------
 
::
 
$Id: tren.rst,v 1.138 2010/03/19 18:47:17 tundra Exp $
$Id: tren.rst,v 1.139 2010/03/19 20:02:37 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren