diff --git a/tren.rst b/tren.rst index 6c933fa..080acfe 100644 --- a/tren.rst +++ b/tren.rst @@ -373,6 +373,11 @@ because you can always synthesize it with ``/F/./E/`` +``/G/ File or directory primary group name`` + + This token is replaced with the name of the + primary group to which the file belongs. + ``/I/ File or directory creation date`` This token is replaced with the date of creation of the @@ -391,26 +396,45 @@ of the file or directory being renamed. It is in ``HH:MM:SS`` format. +``/U/ File or directory owner name`` + + This token is replaced with the name of the + file or direcotry's owner. + + Sequence Renaming Tokens ------------------------ -Sometimes it's useful to rename files or directories not based on -their original names. Instead, it can be useful to rename them - in -whole or part, based on some *property they possess* like the date or -time of creation, the size of the file, who owns it, and so on. This -is the purpose of *sequence renaming tokens*. +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/``, +``/T/``, and ``/S/`` renaming tokens described in the previous section. -The best way to think of sequence renaming tokens is as *unique -strings* designed to help organize the files or directories you're -renaming based on some *shared property*. The actual order of these -strings reflects something about that shared property. +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, +you might want to order the files from oldest to newest with a naming +convention like:: + + file-1.txt + file-2.txt + file-3.txt + +This guarantees uniqueness in the final name and also sees to it that +a sorted directory listing will show you the files or directories in +the order you care about. + +This is the purpose of *sequence renaming tokens*. They give you +various ways to create sequences that can be embedded in the final +file or directory name. General Format Of Sequence Renaming Tokens ------------------------------------------ - Sequence renaming tokens have the following general format:: +Sequence renaming tokens consist of three descriptive components and +have the following general format:: - // + // where, ordering flag: @@ -420,40 +444,39 @@ type: - D sequence on file creation date - G sequence on file's group membership + D sequence on file creation date & time + O sequence on the command line file order S sequence on file size T sequence on file creation time within a given day - U sequence on file's owner - empty sequence on order of file renaming - Count Pattern Format -------------------- -In each of the cases below, the counting pattern is mandatory and -describes two things: The number of digits to use, and the starting -number in the sequence. Examples:: +The counting pattern is used to specify two things: The width of the +sequence string, and the starting value for the sequence. Examples:: 0001 -> 0001, 0002, 0003, ... 0000 -> 0000, 0001, 0002, ... 03 -> 03, 04, 05, ... -You do not have to use a ``0`` to indicate the number of digits to -use. 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.:: +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.:: - xxx3 -> xxx3, xxx4, xxx5, ... - -+8 -> -+8, -+9, -10, -11, ... + xxx3 -> xxx3, xxx4, xxx5, ... 9999, xxx3, xxx4, ... + -+8 -> -+8, -+9, -10, -11, ... 999, -+8, -+9, ... You are not restricted to numbers in a counting pattern. Letters may also be used. **tren** will preserve the case you specify in the -template when creating sequences like this.:: +template when creating sequences like this:: - 000a -> 000a, 000b, 000c, ... - ---X -> ---X, ---Y, ---Z, --AA + 000a -> 000a, 000b, 000c, ... zzzz, 000a, ... + ---Y -> ---Y, ---Z, --AA, ... ZZZZ, ---Y, ---Z, ... + +Notice that when a sequence "rolls over", the next value is the +*initial sequence value you specified*. @@ -585,7 +608,7 @@ :: - $Id: tren.rst,v 1.120 2010/01/16 20:53:08 tundra Exp $ + $Id: tren.rst,v 1.121 2010/01/18 23:43:36 tundra Exp $ You can find the latest version of this program at: