diff --git a/tren.rst b/tren.rst index f6d9769..cb6f8f8 100644 --- a/tren.rst +++ b/tren.rst @@ -132,6 +132,23 @@ target, the file or directory that already exists with that name will be lost!*. + -b Turn off backups during forced renaming. + + (*Default*: Do Backups) + + + Ordinarily, **tren** will refuse to do a renaming if the new + name for a file- or directory already exists. You can + override this with the ``-f`` (forced renaming) option. By + default, forced renaming makes a backup copy of the existing + file (by appending ``.backup`` to its name or some other + suffix you specify with the ``-S`` option) before doing the + renaming. This prevents existing files from being lost due to + a renaming. The ``-b`` option *inhibits backups* and allows + renaming over existing file- and directory names, thereby + losing the original file- or directory. + + -C Do case-sensitive renaming (*Default*: This is the program default) @@ -935,9 +952,81 @@ Forcing Renaming ================ +By default, **tren** will not allow you to perform a renaming operation +if the new name already exists. For example, say you have three files, +``a``, ``aa``, and ``b``, and you try this:: + + tren.py -r a=b a aa b + +**tren** will skip the renaming of file ``a`` because a file named +``b`` already exists. It will, however, continue to run and rename +``aa``, to ``ba``. + +This is designed to prevent you from accidentally clobbering files +that already exist. You can, however, override this default behavior +and *force* the renaming to take place in such situations, using the +``-f`` option. Even then, the existing file isn't lost, it is simply +*renamed itself* by appending the suffix ``.backup`` to its original +name. That way, if you made a mistake, you haven't lost the original +file. So, in our example above, the command becomes:: + + tren.py -fr a=b a aa b + +When it's done, we end up with these files:: + + b # The original 'a' file + b.backup # The original 'b' file + ba # The original 'aa' file + + +If you don't like the suffix, ``.backup``, you can change it to any +string (of length 1 or greater) via the ``-S`` option:: + + tren.py -S .bku -fr a=b a aa b + +Now the backed up file will be named ``b.bku``. + +**tren** will even backup files that are themselves backups. This can +be handy if your renaming request ends up mapping more than one file- or +directory name to the same new name:: + + tren.py -fr =newname a b c + +This produces files named:: + + newname # The original 'c' file + newname.backup # The original 'b' file + newname.backup.backup # The original 'a' file + + +You can inhibit this behavior and prevent backups with the ``-b`` +option. This effectively *erases the original file- or directory of +that name*. This is **very dangerous** and should rarely be used. +It's better to do the backups and delete them later when you're sure +you do not need them. The underlying operating system rules for +renaming will still apply in this case. For instance, most OSs will +not allow you rename a file over the name of an existing directory and +vice versa. + +.. NOTE:: The Unix ``mv`` command will allow you to move a file + *into* a directory:: + + mv file dir + + However, this is an ``mv`` "move" semantic, and is not + properly a renaming operation. The underling file system + will not permit a file to be renamed over a directory or + vice versa. **tren** reflects this OS semantic ... it's + not intended to be a reimplementation of ``mv``. + + Ignoring Case ============= + + + + The Strange Case Of Mac OS X And Windows ======================================== @@ -1622,7 +1711,7 @@ :: - $Id: tren.rst,v 1.155 2010/03/26 20:15:41 tundra Exp $ + $Id: tren.rst,v 1.156 2010/03/29 03:00:47 tundra Exp $ You can find the latest version of this program at: