Fork: 0
tundra / tren
Browse code
First complete, release-ready documentation.
master
1 parent 430bae4 commit 6c1ca5ffe695f4c8114cc51c3f38f5d80c21f7b3
@tundra tundra authored on 23 Apr 2010
Patch
Unified Split
Showing 1 changed file
View
478
■■■■■
 tren.rst
 
**tren** is a powerful command line file/directory renaming tool. It
implements a variety of sophisticated renaming features than can be a bit
complex to learn. For this reason, this document is split into two
general sections: `REFERENCE`_ and `TUTORIAL AND DESCRIPTION`_. If
general sections: "`REFERENCE`_" and "`TUTORIAL AND DESCRIPTION`_". If
you are new to **tren**, start by studying the latter section first.
It will take you from very simple- to highly complex **tren** renaming
operations. Once you've got a sense of what
**tren** can do, the reference section will be handy to look up
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
whereas the ``B=cc`` request would only replace
``B``.
 
-S suffix Suffix to append when making backup copies of existing
targets.
As **tren** runs, it produces a variety of diagnostic and
status information. There are a number of options you can
use to control how this works:
 
-q Set's "quiet" mode and suppresses everthing except
error messages.
 
-w # Tells **tren** to wrap lines after ``#`` characters have been
printed. If you're capturing output to a log, set this to a
very high number like 999 to inhibit line wrapping.
-q Sets "quiet" mode and suppresses everthing except
error messages.
 
-w num Tells **tren** to wrap lines after ``num`` characters have been
printed. If you're capturing output to a log, set this to a
very high number like 999 to inhibit line wrapping.
 
Error and debug messages are sent to ``stderr``. Normal informational
messages are sent to ``stdout``. If you want to capture them both in
a log, try something like this (depending on your OS and/or shell)::
exceeded, it suspects a circular include and will issue an error
message to that effect and exit.
 
You can insert include options anywhere you like on the command line
and you can have as many as you like (up to a VERY large number you'll
and you can have as many as you like (up to a large number you'll
never hit in practice). Each include reference will be replaced with
the contents of that file *at the position it appears on the command
line*.
 
 
Note that you cannot specify individual, non-adjacent instances.
There is no way to use a single **tren** command to replace, say, the
only the 2nd and the 4th instance of an ``old`` string. Doing that
requires two renaming requests. The good news is that we can do them
both on a single **tren** invocation.
requires two renaming requests. As we'll see in the section below,
the good news is that we can do them both on a single **tren**
invocation.
 
 
Multiple Substitutions
======================
you like (.... well, up to the length limit imposed by your operating
system and shell, anyway). As we just saw, this can be handy when
a single renaming request can't quite do everything we want.
 
BUT ... there's a catch. In designing your renaming requests,
you have to keep in mind that **tren** processes the command
line *from left to right*, incrementally constructing the new name
as it goes. For instance::
BUT ... there's a catch. In designing your renaming requests, you
have to keep in mind that **tren** processes the command line *from
left to right*, incrementally constructing the new name as it goes.
That is, the leftmost renaming request operates on the original file-
or directory name. The next renaming request to the right operates on
*that* new name, and so on. In other words, *each renaming request
modifies the name produced thus far by all the renaming requests to
the left of it on the command line*.
 
For instance::
 
tren.py -r foo=bar -r foo=baz foo1-foo2-foo3.foo4
 
Produces ... wait a second ... why on earth are there two renaming
5) Resolve any renaming tokens found in either the ``old`` or
``new`` portions of the renaming request.
 
At this point, both ``old`` and ``new`` are nothing more than
simple strings, although ``old`` may be interpreted as a
simple strings (although ``old`` may be interpreted as a
regular expression rather than literally if the option to do so
is in effect.
is in effect).
 
6) Process each file found on the command line in left to right
order, applying each renaming request, in the order it appeared
from left to right on the command line.
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: ``\=``.
a regular expression, it has to be escaped like this: ``\=``. (You
can also get around this by changing the ``old/new`` separator
character with the ``-R`` option.)
 
As with literal string renaming, regular expression renaming requests
honor both the case sensitivity options (``-C`` and ``-c``) as well
as the instance option, ``-i``. So, for example::
what you want to do. You have 4 possible choices::
 
N, n, or Enter - No, don't rename this file
Y, y - Yes, rename the file
! - Yes, rename this and all remaining files without asking any more
! - Yes, rename everything further without asking
Q, q - Quit the program
 
 
There is one slight subtlety here to watch for when doing forced
something like this::
 
tren.py -xr '/$SYSNAME/.*bku$=/FNAME/.old' *
 
If your system name was "matrix", then the command above would only
If your system name was ``matrix``, then the command above would only
rename files whose names began with ``matrix`` and ended with ``bku``.
If your system name were "morton", then the command above would only
If your system name were ``morton``, then the command above would only
rename files whose names began with ``morton`` and ended with ``bku``.
 
Notice that we combined a reference to an environment variable within
a regular expression. This was done to do the match on "names
 
 
**tren** has many other kinds of renaming tokens. Their structure and
use is described in some detail in the section below entitled
`Renaming Tokens: The Gory Details`_.
"`Renaming Tokens: The Gory Details`_".
 
 
Renaming Token Pitfalls
=======================
As we saw in earlier sections, **tren** command line option and file
name interaction can be tricky. It can depend on order and on whether
the various renaming requests "collide" with each other as a new file
name is computed. A similar potential collision exists between
renaming tokens and renaming requests. Recall from `More About
Command Line Pitfalls`_ that renaming tokens are resolved *before* a
renaming tokens and renaming requests. Recall from "`More About
Command Line Pitfalls`_" that renaming tokens are resolved *before* a
renaming request is processed. This means that the string
substitution (literal or regular expression) of the renaming operation
can *conflict with the characters returned when the renaming token was
resolved*. For example, suppose we do this::
 
``My`` gets replaces with ``Your``, but as soon as the second renaming
request is processed, the whole string is thrown away and replaced
with the final name ``New-MyFile.txt``. This is yet another
example of, **"The Rightmost Renaming Request Wins!"**
example of, **"The Rightmost Renaming Request Wins"**.
 
 
Renaming Tokens: The Gory Details
=================================
- A sequence that reflects some ordering principle
 
Renaming tokens are delimited by ``/`` characters, in the form::
 
/RenTokenName/
/RentokenName/
 
**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.
Every file will be renamed in the form of::
 
original_name-YYYY-length # Example: myfile-2010-4099
 
In short, attributes are just string substitutions wherein the string
tells you something about the file or system on which you're working.
So... *attributes are string substitutions wherein the string
tells you something about the file or system on which you're working*.
 
"Sequences", on the other hand, are just *numbers that represent some
ordering principle*. Say you use the sequence renaming token ordered
by size, ``/+SIZE::001/`` to rename 10 files of different sizes::
 
Where, ``01-original_name`` will be the *shortest length* file
and ``10-original_name`` will be the *longest length* file.
 
In short, sequences are just strings of numbers used to put
things in some order.
So... *sequences are strings of numbers used to put things in some
order*.
 
You can always tell the difference between an attribute- and sequence
renaming token, because sequence renaming tokens always start with
either a ``+`` or ``-`` sign (to indicate ascending or descending
to 0. Avoid using these tokens on Windows systems, since
these will return the same value for every file- or
directory.
 
``/DEV/ Returns File- Or Directory's Device ID``
- ``/DEV/ Returns File- Or Directory's Device ID``
 
This is the ID of the device containing the file being
renamed. You might want to rename files so that all the
files on a given device start with the same key. That
The filenames are still preserved in our renaming reqest
above, now they're just preceded by the device ID of the
where they live with a trailing ``-`` separator.
 
``/FNAME/ Returns Original File- Or Directory Name``
- ``/FNAME/ Returns Original File- Or Directory Name``
 
This is the name of the file- or directory you are
renaming *before* you apply any renaming requests. This
allows you to create new names based, in part, on the old
name::
 
tren.py -r=/FNAME/-suffix file | dir ... # Adds "-suffix" to the end of original name
tren.py -r=prefix-/FNAME/ file | dir ... # Adds "-prefix" to start of original name
tren.py -r /FNAME/=newname file | dir ... # Same as "-r=newname"
tren.py -r /FNAME/=/FNAME/ file | dir ... # Does nothing since old- and newname are the same
 
``/GID/ Returns File- Or Directory's Group ID``
tren.py -r=/FNAME/-suffix ... # Adds "-suffix" to original name
tren.py -r=prefix-/FNAME/ ... # Adds "-prefix" to original name
tren.py -r /FNAME/=newname ... # Same as "-r=newname"
tren.py -r /FNAME/=/FNAME/ ... # Does nothing since old- and newname are the same
 
- ``/GID/ Returns File- Or Directory's Group ID``
 
This is the number for the group to which the file- or
directory belongs. One way to use this is to prepend it
to every file name, thereby having all files (and or
directory listing::
 
tren.py -r=/GID/-/FNAME/ *
 
``/GROUP/ Returns File- Or Directory's Group Name``
- ``/GROUP/ Returns File- Or Directory's Group Name``
Essentially the same as ``/GID/`` except it returns the
*name* of the group rather than the number. Again, this
is useful when clustering names together in a sorted
directory listing::
 
tren.py -r=/GROUP/-/FNAME/ *
 
``/INODE/ Returns File- Or Directory's Serial Number``
- ``/INODE/ Returns File- Or Directory's Serial Number``
 
This is typically an identifier to the directory entry
for the file- or directory being renamed. ``/DEV/`` and
``/INODE/`` taken together provide a unique systemwide
identifier for the file- or directory being renamed.
 
``/MODE/ Returns File- Or Directory's Permissions``
- ``/MODE/ Returns File- Or Directory's Permissions``
 
This is a numeric string that represents the permissions
of the file- or directory being renamed in standard Unix
format.
 
``/NLINK/ Returns Number Of Links To File- Or Directory Being Renamed``
- ``/NLINK/ Returns Number Of Links To File- Or Directory Being Renamed``
 
Most operating systems allow a single file to have
multiple names. These names are "linked" to the instance
of the file. This replacement token is a numeric string
representing the number of such links.
 
``/SIZE/ Returns File- Or Directory's Length In Bytes``
- ``/SIZE/ Returns File- Or Directory's Length In Bytes``
 
This is handy if you want a sorted directory listing to
list all the files of the same size together. You simply
prepend the file- or directory's length onto its name::
 
Now all of the files of, say, length 23 will group
together in a sorted directory listing.
 
``/UID/ Returns File- Or Directory's User ID``
- ``/UID/ Returns File- Or Directory's User ID``
 
This is the number for the user that owns the file- or
directory being renamed. One way to use this is to
prepend it to every file name, thereby having all files
together in a sorted directory listing::
 
tren.py -r=/UID/-/FNAME/ *
 
``/USER/ Returns File- Or Directory's User Name``
- ``/USER/ Returns File- Or Directory's User Name``
Essentially the same as ``/UID/`` except it returns the
*name* of the user rather than the number. Again, this
is useful when clustering names together in a sorted
 
Time-Related Attribute Renaming Tokens
======================================
 
Modern operating system actually maintain three different kinds of
such timestamps, ``ATIME``, ``CTIME``, ``MTIME``:
Modern operating system maintain three different kinds of timestamps
for files and directories, ``ATIME``, ``CTIME``, and ``MTIME``:
 
``ATIME`` refers to the last time the file- or directory was
*accessed*.
 
you need them. They are identically named, except that the first
letter of each of the time-related attribute tokens indicates which of
the three timestamps above is used to compute the value:
 
 
``/ADAY/, /CDAY/, /MDAY/ Returns Timestamp's Day Of The Month``
- ``/ADAY/, /CDAY/, /MDAY/ Returns Timestamp's Day Of The Month``
 
Returns the day of the month of the timestamp in ``dd`` format.
 
``/AHOUR, /CHOUR/, /MHOUR/ Returns Timestamp's Hour Of The Day``
- ``/AHOUR, /CHOUR/, /MHOUR/ Returns Timestamp's Hour Of The Day``
 
Returns the hour of the day of the timestamp in ``hh`` format.
 
``/AMIN/, /CMIN/, /MMIN/ Returns Timestamp's Minute Of The Hour``
- ``/AMIN/, /CMIN/, /MMIN/ Returns Timestamp's Minute Of The Hour``
 
Returns the minute of the hour of the timestamp in ``mm`` format.
 
``/AMON/, /CMON/, /MMON/ Returns Timestamp's Month Of The Year``
- ``/AMON/, /CMON/, /MMON/ Returns Timestamp's Month Of The Year``
 
Returns the month of the year of the timestamp in ``mm`` format
 
``/AMONTH, /CMONTH/, /MMONTH/ Returns Timestamp's Name Of The Month``
- ``/AMONTH, /CMONTH/, /MMONTH/ Returns Timestamp's Name Of The Month``
 
Returns the name of the month of the timestamp in ``Nnn`` format.
 
``/ASEC/, /CSEC/, /MSEC/ Returns Timestamp's Seconds Of The Minute``
- ``/ASEC/, /CSEC/, /MSEC/ Returns Timestamp's Seconds Of The Minute``
 
Returns the seconds of the minute of the timestamp in ``ss`` format.
 
``/AWDAY, /CWDAY/, /MWDAY/ Returns Timestamp's Name Of The Day``
- ``/AWDAY, /CWDAY/, /MWDAY/ Returns Timestamp's Name Of The Weekday``
 
Returns the name of the day of the timestamp in ``Ddd`` format.
 
``/AYEAR, /CYEAR/, /MYEAR/ Returns Timestamp's Year``
- ``/AYEAR, /CYEAR/, /MYEAR/ Returns Timestamp's Year``
 
Returns the year of the timestamp in ``yyyy`` format.
 
 
runtime environment. Notice that, because command interpreters
(shells) on various systems work differently, the first two of these
have to be quoted in different ways.
 
``/$ENV/ Environment variable``
- ``/$ENV/ Environment variable``
 
This token is replaced with the value of the
environment variable ``ENV``. If that variable does
not exist, the token is replaced with an empty string::
This prepends the organization's name to everything in
the current directory.
 
 
``/`cmd`/ Arbitrary command execution``
- ``/`cmd`/ Arbitrary command execution``
 
This token is replaced with the string returned by
executing the ``cmd`` command. Note that newlines are
stripped from the results, since they don't belong in
you're doing with this renaming
token.
.. Note:: **MORE ABOUT QUOTING** ``/$ENV/`` **AND** ``/`cmd`/`` **SYSTEM RENAMING TOKENS**
.. Tip:: **MORE ABOUT QUOTING** ``/$ENV/`` **AND** ``/`cmd`/`` **SYSTEM RENAMING TOKENS**
 
Both of these constructs are supported directly from most
Unix command shells. That is, most Unix shells will
themselves dereference constructs like ``$ENV`` and
 
tren.py -r=/FNAME/-"/`command option1 option2 argument`/" files ...
 
 
``/RAND#/ Random Number Generator``
- ``/RAND#/ Random Number Generator``
 
This generates a (quasi) random number string, ``#``
digits wide.
 
Establishes the first value in the counting
sequence and/or provides a string to format
the count.
 
Note that there is no space between the Ordering flag and Type.
Note that there is no space between the *Ordering* flag and *Type*.
 
An *Ordering* flag is mandatory. It will either be ``+`` to indicate
an ascending count or ``-`` to indicate a descending count.
 
The *Type* is mandatory. All available types are described in the
section below entitled, `Types Of Sequence Renaming Tokens`_.
The *Type* is mandatory. These are documented in the section
below entitled, "`Types Of Sequence Renaming Tokens`_".
 
The *Counting Alphabet* is optional. Counting alphabets are ways to
count in different bases and even to use something other than just
numbers to represent the count. These are described in the section
below entitled, `Let's Learn The Alphabet`_.
below entitled, "`Let's Learn The Alphabet`_".
 
If you omit naming a specific alphabet, **tren** will default to
counting in Decimal. Note that you *cannot* omit the alphabet
delimiters, so the correct form of a sequence renaming token then
 
A *Counting Pattern* is optional. Counting patterns are used to do
two things: Set the initial value for the count and Describe the
layout of how the count should look. This is described in the section
below entitled, `Counting Pattern Format`_.
below entitled, "`Counting Pattern Format`_".
 
If you omit a counting pattern, **tren** will start counting from the
zero-th "number" in your chosen alphabet, producing a counting pattern
as "wide" as necessary to count all the items being renamed. In that
Decimal - Counting in Base 10 using numbers
HexLower - Counting in Base 16 using numbers and lower case letters
HexUpper - Counting in Base 16 using numbers and upper case letters
Lower - Counting in Base 26 using lower case letters
LowerUpper - Counting in Base 52 using first lower- then upper case letters
LowerUpper - Counting in Base 52 using lower- then upper case letters
Upper - Counting in Base 26 using upper case letters
UpperLower - Counting in Base 52 using first upper- then lower case letters
UpperLower - Counting in Base 52 using upper- then lower case letters
 
 
.. TIP:: **The difference between a "base" and a "symbol set".**
 
 
So, by mixing characters that are both in- and out of the counting
alphabet in a counting pattern, you "prime" the sequence renaming
token to start counting with a certain string. This works for all
alphabets, any base, and any symbol set::
token to start counting with a certain string. Notice that you
can do this in *any* position within the pattern. Say you do
this::
 
tren.py -r=/+CMDLINE::x1x4/ *
 
This will produce a counting sequence like this::
 
x1x4
x1x5
...
x110
...
x200
 
In other words, a character in any position of the pattern that is
in the counting alphabet will be added to the count.
 
This works for all alphabets, any base, and any symbol set::
 
tren.py -r=/+FNAME/:Upper:+0S/ *
 
Yields new file names::
Note that those associated with the various OS timestamps begin with
the corresponding first letter:
 
 
``/+-ADATE:Alphabet:FormatField/ Sequence based on atime timestamp WITHIN the same date``
 
``/+-CDATE:Alphabet:FormatField/ Sequence based on ctime timestamp WITHIN the same date``
 
``/+-MDATE:Alphabet:FormatField/ Sequence based on mtime timestamp WITHIN the same date``
 
These return sequences *within* a given day. This enables
renaming constructs like::
 
tren.py -r=/MYEAR//MMON/MDAY/-/+MDATE::001/ *
 
Yielding files named::
 
20100305-001
20100305-002
20100305-003
20100316-001
20100316-002
20100316-003
...
- ``/+-ADATE:Alphabet:Pattern/ Sequence based on atime WITHIN the same date``
 
- ``/+-CDATE:Alphabet:Pattern/ Sequence based on ctime WITHIN the same date``
 
- ``/+-MDATE:Alphabet:Pattern/ Sequence based on mtime WITHIN the same date``
 
These return sequences *within* a given day. This enables
renaming constructs like::
 
tren.py -r=/MYEAR//MMON/MDAY/-/+MDATE::001/ *
 
Yielding files named::
 
20100305-001
20100305-002
20100305-003
20100316-001
20100316-002
20100316-003
...
 
``/+-ATIME:Alphabet:FormatField/ Sequence based on atime timestamp``
 
``/+-CTIME:Alphabet:FormatField/ Sequence based on ctime timestamp``
 
``/+-MTIME:Alphabet:FormatField/ Sequence based on mtime timestamp``
 
These return sequences in absolute timestamp order. For example::
 
touch foo
touch bar
touch baz
tren.py -r =/+MTIME::/-/FNAME
 
Yields::
 
foo-0
bar-1
baz-2
 
 
``/+-CMDLINE:Alphabet:FormatField/ Sequence based on the order of appearance on the command line``
 
This is nothing more than the command line order::
 
tren.py -r=/+CMDLINE/-/FNAME::01/-/FNAME/ z b a
 
Yields::
 
01-z
02-b
03-a
 
 
``/+-DEV:Alphabet:FormatField/ Sequence based on the device ID number on which the file- or directory resides``
 
This is the a sequence ordered by which device ID contains the file-
or directory to be renamed.
 
This is not supported on Windows and defaults to an alphabetic
sequence equivalent to ``/+-FNAME.../``.
 
 
``/+-FNAME:Alphabet:FormatField/ Sequence based on alphabetic order of all targets on the command line``
 
This returns a sequence based on the alphabetic order of everything
you've named for renaming. Note that this is done on *the fully
qualified path name for each argument*, not just the file- or
directory name itself::
 
tren.py -r=/+FNAME::/-/FNAME/ a/z b/b
 
Yields::
 
a/0-z
b/1-b
 
This is because the original file name ``a/z`` sorts alphabetically
before ``b/b``.
 
 
``/+-GID:Alphabet:FormatField/ Sequence based on the group ID number``
 
This returns a sequence ordered by the ID number of the group to which
the file- or directory belongs.
 
This is not supported on Windows and defaults to an alphabetic
sequence equivalent to ``/+-FNAME.../``.
 
 
``/+-GROUP:Alphabet:FormatField/ Sequence based on the group name``
 
This returns a sequence ordered by the name of the group to which the
file- or directory belongs.
 
This is only supported on Windows if the ``win32all`` Python extensions
are installed. Otherwise, this defaults to an alphabetic sequence equivalent to ``/+-FNAME.../``.
 
``/+-INODE:Alphabet:FormatField/ Sequence based on the inode number``
 
This returns a sequence ordered by the file- or directory inode numbers.
 
This is not supported on Windows and defaults to an alphabetic
sequence equivalent to ``/+-FNAME.../``.
 
 
``/+-MODE:Alphabet:FormatField/ Sequence based on permissions``
 
This returns a sequence ordered by the file- or directories permissions
value.
 
 
``/+-NLINK:Alphabet:FormatField/ Sequence based on the nlink count``
 
This returns a sequence ordered by the number of links associated
with the file- or directory.
 
This is not supported on Windows and defaults to an alphabetic
sequence equivalent to ``/+-FNAME.../``.
 
 
``/+-SIZE:Alphabet:FormatField/ Sequence based on size``
 
This returns a sequence ordered by the size of each file- or
directory.
 
``/+-UID :Alphabet:FormatField/ Sequence based on the user ID number``
 
This returns a sequence ordered by the ID number of the user that
owns the file- or directory.
 
This is not supported on Windows and defaults to an alphabetic
sequence equivalent to ``/+-FNAME.../``.
 
 
``/+-USER:Alphabet:FormatField/ Sequence based on user name``
 
This returns a sequence ordered by the name of the user that owns
the file- or directory.
 
This is only supported on Windows if the ``win32all`` Python extensions
are installed. Otherwise, this defaults to an alphabetic sequence equivalent to ``/+-FNAME.../``.
- ``/+-ATIME:Alphabet:Pattern/ Sequence based on atime timestamp``
 
- ``/+-CTIME:Alphabet:Pattern/ Sequence based on ctime timestamp``
 
- ``/+-MTIME:Alphabet:Pattern/ Sequence based on mtime timestamp``
 
These return sequences in absolute timestamp order. For example::
 
touch foo
touch bar
touch baz
tren.py -r =/+MTIME::/-/FNAME
 
Yields::
 
0-foo
1-bar
2-baz
 
 
- ``/+-CMDLINE:Alphabet:Pattern/ Sequence based on the order of appearance on the command line``
 
This is nothing more than the command line order::
 
tren.py -r=/+CMDLINE/-/FNAME::01/-/FNAME/ z b a
 
Yields::
 
01-z
02-b
03-a
 
 
- ``/+-DEV:Alphabet:Pattern/ Sequence based on the device ID number on which the file- or directory resides``
 
This is the a sequence ordered by which device ID contains the file-
or directory to be renamed.
This is not supported on Windows and defaults to an alphabetic
sequence equivalent to ``/+-FNAME.../``.
- ``/+-FNAME:Alphabet:Pattern/ Sequence based on alphabetic order of all targets on the command line``
This returns a sequence based on the alphabetic order of everything
you've named for renaming. Note that this is done on *the fully
qualified path name for each argument*, not just the file- or
directory name itself::
 
tren.py -r=/+FNAME::/-/FNAME/ a/z b/b
 
Yields::
 
a/0-z
b/1-b
 
This is because the original file name ``a/z`` sorts alphabetically
before ``b/b``.
 
- ``/+-GID:Alphabet:Pattern/ Sequence based on the group ID number``
 
This returns a sequence ordered by the ID number of the group to which
the file- or directory belongs.
This is not supported on Windows and defaults to an alphabetic
sequence equivalent to ``/+-FNAME.../``.
 
 
- ``/+-GROUP:Alphabet:Pattern/ Sequence based on the group name``
 
This returns a sequence ordered by the name of the group to which the
file- or directory belongs.
This is only supported on Windows if the ``win32all`` Python extensions
are installed. Otherwise, this defaults to an alphabetic sequence equivalent to ``/+-FNAME.../``.
 
- ``/+-INODE:Alphabet:Pattern/ Sequence based on the inode number``
 
This returns a sequence ordered by the file- or directory inode numbers.
This is not supported on Windows and defaults to an alphabetic
sequence equivalent to ``/+-FNAME.../``.
 
 
- ``/+-MODE:Alphabet:Pattern/ Sequence based on permissions``
 
This returns a sequence ordered by the file- or directories permissions
value.
 
 
- ``/+-NLINK:Alphabet:Pattern/ Sequence based on the nlink count``
 
This returns a sequence ordered by the number of links associated
with the file- or directory.
 
This is not supported on Windows and defaults to an alphabetic
sequence equivalent to ``/+-FNAME.../``.
 
 
- ``/+-SIZE:Alphabet:Pattern/ Sequence based on size``
 
This returns a sequence ordered by the size of each file- or
directory.
 
- ``/+-UID :Alphabet:Pattern/ Sequence based on the user ID number``
 
This returns a sequence ordered by the ID number of the user that
owns the file- or directory.
 
This is not supported on Windows and defaults to an alphabetic
sequence equivalent to ``/+-FNAME.../``.
 
 
- ``/+-USER:Alphabet:Pattern/ Sequence based on user name``
 
This returns a sequence ordered by the name of the user that owns
the file- or directory.
This is only supported on Windows if the ``win32all`` Python extensions
are installed. Otherwise, this defaults to an alphabetic sequence equivalent to ``/+-FNAME.../``.
 
 
COMMON TASKS AND IDIOMS
-----------------------
- Save the output from your **tren** runs in logs. That way, if you
have to unwind a renaming gone bad, you'll have a record of what was
done.
 
- The use of ``-bf`` is **strongly** discouraged and is provided only
- The use of ``-bf`` is **STRONGLY DISCOURAGED** and is provided only
for the most sophisticated and careful users.
 
 
 
-----------------------------
 
::
 
$Id: tren.rst,v 1.182 2010/04/23 16:13:45 tundra Exp $
$Id: tren.rst,v 1.183 2010/04/23 18:40:15 tundra Exp $
 
You can find the latest version of this program at:
 
http://www.tundraware.com/Software/tren