NAME
----

**trm** - A Safer Delete Utility


SYNOPSIS
--------

``trm.sh -cehistvx -g graveyard [file|dir] ...``


DESCRIPTION
-----------

``trm`` is a file- and directory removal tool with several key features:

  - Files are not actually removed, but put in a "graveyard" where
    they can later be retrieved.  By default, this is in
    ``~/.graveyard``, but this can be overriden on the command line
    with the ``-g`` option.

  - There is a "test mode" which doesn't actually do anything, but
    only shows you what the program *would do* if it actually executed,

  - Deleted items are stored in the graveyard in the same directory hierarchy
    they were originally in.

  - By default, deleted items have a datetime stamp or "serial number"
    appended to them.  This allows the graveyard to accumulate different
    versions of a file- or directory tree as they are deleted over time.

  - ``trm`` can also be use to simply copy a set of files- and/or directories
    into the graveyard, without actually removing them from their original
    location.  This is handy if you want to take advantage of the serial
    number capability and keep versioned "deletions" around, but not actually
    remove the original files- or directories.

  - Delete or copies can be invoked interactively so you can select
    which of the targets you actually want affected.

  - You can either run the program as a standalone utility - via the
    ``trm.sh`` program - Or, you can source it - ``. trm,sh``.  This
    loads the ``trm`` shell function into the current shell context for
    subsequent use from the command line or another program.

  - You can put commonly used command line options in the ``$TRM`` environment
    variable.  For instance, you may want to default to test mode operation by
    doing something like ``export TRM="-t"``.


OPTIONS
-------

You can override the program's default behavior with a number of command
line options:


  -c            copy targets to graveyard, don't remove them
  -e            empty the current graveyard (permanent removal)
  -h            display this help screen
  -g graveyard  use named graveyard instead of default
  -i            interactive removal/copy
  -s            don't generate serial number suffixes
  -t            test mode, just show what would be done
  -v            verbose mode - noisy output
  -x            execute, overrides previous -t


OPERATING NOTES
---------------

- Note that, in these examples, ``trm.sh`` means we're invoking the
  program as a standalone utility that is presumably somewhere on your
  ``$PATH``.  ``trm`` means you've sourced it previously and it's
  being called as shell function from your current command line
  context.

- You can use ``trm`` just like you do conventional ``rm``::

    trm /tmp/foo /home/me/bar

  So the files/directories called ``foo`` and ``bar`` would be
  "removed` from their current location and placed in
  ``~./.graveyard/tmp/foo`` and ``~./.graveyard/home/me/bar``
  respectively.  If the required directory structure does not exist in
  the graveyard, ``trm`` will create it automatically.

- Directory removal or copy is always recursive.

- Options are processed left-to-right and take effect in that same
  order.  For example, ``trm.sh -ve`` will clear out the graveyard and
  report on everything it is removing.  However, ``trm.sh -ev`` will
  not because the deletions will occur before the verbose option is
  recognized.

- If you are using multiple graveyards, you can use this property
  to your advantage to clear them all with one command::

    trm -v -g gy1 -e -g gy2 -e -g gy3 -e ....

- Serial numbers are appened to the target *as named on the command
  line*.  If you delete a file, then it wil go into the graveyard as
  ``file.serialnumber``.  Similarly, a directory goes into the
  graveyard as ``dir.serialnumber``.  However, the names of anthing
  *within* that directory, are left untouched.  This allows you to
  decide at what level of detail you want delete versioning to be
  maintained.

- If one of your delete/copy targets is a symlink, it will simply
  be moved or copied to the graveyard as-is.  However, if you
  refer to a symlink somewhere in the path to a target, it *will*
  be expanded.  That target will be moved or copied to a
  directory tree within the graveyard that mirrors the canonical
  location of the original target.

  For example, say you have a symlink such as ``/local ->  /usr/local``.
  Then::

    trm /local  # Moves the symlink to ~/.graveyard/local

 But::

    trm /local/bin/x # Moves x to ~/,graveyard/usr/local/bin/x


BUGS AND MISFEATURES
--------------------

None known as of this release.


COPYRIGHT AND LICENSING
-----------------------

**trm** is Copyright (c) 2016 TundraWare Inc., Des Plaines, IL 60018 USA

For terms of use, see the ``trm-license.txt`` file in the
program distribution.

If you install **trm** on a FreeBSD system using the 'ports'
mechanism, you will also find this file in::

  /usr/local/share/doc/trm

AUTHOR
------

::

   Tim Daneliuk
   tundratundraware.com