README

========================================================================================
                                    TRSH
	 		Copyright 2008 Amithash Prasad                                         
			       Version 3.15-13

	 trsh is free software: you can redistribute it and/or modify         
	 it under the terms of the GNU General Public License as published by   
	 the Free Software Foundation, either version 3 of the License, or      
	 (at your option) any later version.                                    
	                                                                        
	 This program is distributed in the hope that it will be useful,        
	 but WITHOUT ANY WARRANTY; without even the implied warranty of         
	 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          
	 GNU General Public License for more details.                           
	                                                                        
	 You should have received a copy of the GNU General Public License      
	 along with this program.  If not, see <http://www.gnu.org/licenses/>.  

========================================================================================

A safe rm.

MOTIVATION
----------

I wrote this script when I accidentally deleted my homework. Enough Said...

FEATURES
--------

1. trsh follows the freeDesktop.org's Trash specification. What does that mean to the user?
   a. Files you delete using trsh, will be visible to your desktop's (Following 
      freeDesktop like KDE or GNOME of course) trash utility. 
   b. Files you delete using trsh can be undone using your desktop's trash utility.
   c. Files deleted using your desktop's trash utility will be visible to trsh.
   d. Files deleted using your desktop's trash utility can be undone by trsh.

   This is quite important and the reason for the rewrite between 2.x to 3.x.
   I got irritated with trsh 2.x as it was orthogonal to my desktop's trash.

2. You can delete files, undo deleted files and remove specific files from your trash. 

3. You can empty your trash.

4. You can list your trash contents.

5. You can use perl's regex's in most of the operations (Do not bother with it if you
   do not know perl's regex. You can perfectly live without this feature).

6. Each mounted device has its own trash. This means that there will be no costly and
   time consuming moves from one device to another. This was the bane of trsh 2.x where
   when you deleted something on an external hard disk, it was moved to your home
   trash folder! 

7. Installs the alias to rm. So you do not have to learn to use trsh instead of rm. 
   You can continue deleting files thinking that you are using rm!


SETUP
-----
./configure.pl [OPTIONS]
make 
make install

Configure options:
USER=1 performs a user installation, USER=0 (default) Performs a system wide install

SHELL=/path/to/shell (default: $SHELL env variable)
You can provide an option about what shell you want to trsh to be used in.

IPATH="/path/to/trsh.pl" -- specify the path with the name of trsh.pl where you want
to install trsh.pl. default: /usr/bin/trsh.pl for USER=0 and $home/.trsh.pl for USER=1

RPATH="/path/to/*rc" -- specify the path to the *rc file. If not specified, the configure
script will look for a suitable rc file (based on the detected shell) in /etc for USER=0
or in $home for USER=1

MPATH="/path/to/man/files" -- specify the path to the commands man page (default - 
got from `manpath` and a preference is given to /usr/share/man/man1). This option 
is ignored for USER=1, as no man pages are installed for a user installation.

PPATH="/path/to/perl" -- specify the path to perl.
Default: got from the output of `which perl`
This is necessary when your distribution names perl as something else, or perl is 
not installed in a location present in $PATH.

Keep a lookout at the output of configure. It is right most of the time. But if you
feel it is not, try to configure it with your own options. I have tried it on fedora,
suse and ubuntu and you will not need any other options (USER is nice if you do not
have root access).

'make uninstall' To uninstall trsh from your system. 

'make clean' to clean your current directory of temporary files.

If you use an unsupported shell (like the z shell). You need to find out all the 
parameters for that shell like: How does aliases work?, where is the user rc file? 
where is the system wide rc file? etc and try your luck with the manual install 
described in the second point in the NOTES Section.


USAGE
-----

rm [OPTIONS]... [FILES]...

FILES: A list of files to recover or delete.
rm FILES just moves FILES to the trash. By default, directories are not deleted.

OPTIONS:

-u|--undo [FILES]
Undo's a delete (Restores FILES or files matching REGEX from trash). 
Without arguments, the latest deleted file is restored.

-p|--permanent FILES
Instructs trsh to permanently delete FILES and completely bypass the trash

-i|--interactively
Prompt the user before any operation.

-r|--recursive
Allows directories to be deleted.

-v|--verbose
Provide verbose output.

-e|--empty [FILES]
Removed FILES or files matching REGEX from the trash (Permanently).
Without arguments, the trash is emptied. --force option causes trsh
to empty the trash without prompting the user.

-f|--force
Forces any operation:
	deletion   : overrides -i and does not prompt the user for any action.
	             with -p passes the -f flag to /bin/rm
	restore    : will force overwrites of files and will not ask for user permission.
	empty file : will not ask the user's permission for each file.
	empty trash: will not ask for confirmation from the user.


-l|--list
Display the contents of the trash.

--no-color
An option for listing which turns of term colors.

-x|--regex
Considers input as perl regex rather than names or paths.
rm -x REGEX # Delete files matching REGEX
rm -ux REGEX # Recover files in trash matching regex.
rm -ex REGEX # Remove files in trash matching regex.
rm -lx REGEX # List trash contents matching regex.
Note REGEX can be expressed multiple times.
REGEX can be a path with the file name being a regex.
example: "/home/user/test_\\d"

-s|--size
Display the size in bytes of the trash. 
If used along with -l, the trash listing will also display each file's size.

-h|--human-readable
If used along with -s, the file size displayed will be human readable
(KB, MB etc) rather than in bytes.

--help
Displays help.

Deleting Files
--------------

When properly installed, the script is written to mimic rm in all its options.
Even the error messages are mimicked up to a certain point. Thus trsh should
not need any learning to delete files.

rm [-p -f -v -r -i -x] FILE1
rm *
rm /home/user/Desktop/* 

-v makes all operations verbose. So you know what is being deleted.

-p permanently deletes files bypassing the trash.

-f will not ask for permission while deleting files.
   with the -p option, it will pass the -f flag to rm

-r recursively deletes directories. Note this option name (recursive) does 
not make sense but used to match rm's option. 

-i option will ask the user's permission to delete each file.
   is overwridden if the -f flag is also present.

-x Considers all input as Perl's regex. 
   Be _very_ careful when using -x with -p and -f. 

Examples:
rm FILE                   # Moves FILE to Trash
rm -r Directory           # Moves Directory to Trash
rm -f FILE                # deletes FILE does not ask for confirmations (For example, write protected files.)
rm -p FILE                # permanently deletes file
rm -rp DIR                # Permanently deletes DIR
rm -rpf DIR               # Permanently deletes DIR and passes -f to rm.

rm -x "test_[a-z]"        # Deletes all files in current directory matching
                          # test_[a-z]

# -v to any of the above makes the operation verbose.

Refer to the regex section for a more detailed coverage.


Listing files in trash
----------------------

rm -l [-s -h -x --no-color]
rm -l 
lists the trash contents displaying the files in color based on their type.
rm -l --no-color
Lists the trash without colors. Useful for terminals which does not support
colored display.
rm -ls
Lists trash contents with an extra column with the size of each file in bytes
rm -lsh
Same as rm -ls except that the size is displayed in human readable format.
rm -l -x REGEX [REGEX2 REGEX3]
Lists only the files matching REGEX or optionally a list of regex's.
Refer to the regex section for a more detailed coverage.

Size of the trash
-----------------

rm -s [-h]

To view the size of the trash, use the -s option which 
prints the size of the trash in each device in bytes.
specifying the -h option will make the sizes to be printed
in human readable format. 

Undoing trashed files
---------------------

rm -u [-x -v -f] [FILE|REGEX]

rm -u
Restores the _latest_ deleted trashed file(s) to their original location.
Example:
rm test1 test2 test3
rm -u 
will restore test1 test2 and test3.

rm -u FILE [FILE2 FILE3 ...]
Restores the _latest_ copy of FILE (or FILE, FILE2 FILE3 etc) to their
original location. Note, FILE FILE2 FILE3... Can also be the original
path rather than the file/dir name if you want to be more specific.
By specifying the path helps in removing any ambiguity if there
are files in the trash with the same name but coming from different
paths:
example:
rm /home/user/test
rm /home/user/Desktop/test

rm -u test # Recovers to /home/user/Desktop/test as that is the 
latest deleted file with the name "test".
instead if you awnted /home/user/test,
rm -u /home/user/test
will recover that file.

If while recovering a file, another file exists with the same 
name, then trsh will ask the user if they want to overwrite
the file. This is not performed with the -f (--force) flag.

-x option with a regex (or list of regexes) can be specified
to undo files in trash. It can be a path with the name as
a regex. 

Refer to the regex section for a more detailed coverage.

Emptying the trash
------------------

rm -e [-x -f ] [FILES | REGEXES]

rm -e
empties the trash and asks for the user permission before
doing it.
rm -ef empties the trash and does not nag the user.

rm -e FILE
removes all files with the name FILE in the trash (All trashes)
rm -e PATH
Removes all files in the trash with the path PATH (PATH is the original path before deletion).

note different FILE/PATH can be specified together.
Trsh will ask for the user's permission for each file. -f will override this behavior.

rm -ex REGEX [REGEX1 REGEX2]
removes all files in the trash matching REGEX (or REGEX1, REGEX2,...). 

Refer to the regex section for a more detailed coverage.

REGEX
--

Currently Perl's regex which is a better form of POSIX's Regex is supported.
This is done as the script is written in perl and is very easy for me to
evaluate the supplied regex. Please google Perl Regex to know more of the format. 

1. Always use the -v option with -x. This way you will know what is going on. 
   There might be bugs or you might have accidentally specified the wrong 
   regex. So it is nice to know.
2. Never specify -f when removing files from the trash with the -x option. 
   You would want to know what the damn thing is doing. You still can, but
   do it at your own risk, but do use the -v option to at least know if you
   fu*ked up. 

Example typical usages:
deleting all test log files:
rm -x "test.log.\d+"
you could have as well done:
rm -x test.log.*,
   but the regex becomes useful when you do not want to delete files 
   which are named:
   test.log.helloworld

This is the reason, I can say that the -x option for deleting will be the 
least used. Probably more useful restoring multiple files.

Note you can always restore the _latest_ deleted files. 


NOTES
--

1. If you really want to use the mercurial snapshot, then please stick to the revision 
   I have made available for download! Revisions are dime a dozen, and they mean nothing
   (At least for me)!
   I run the tests only for the revision I want to upload to the downloads page.

2. MANUAL INSTALLATION: (These are steps which are followed by the configure and makefile scripts)
   i. Copy trsh.pl to anywhere you like, 
   ii. If you want a manual entry, copy trsh.1.gz to /usr/share/man/man1 (Optional)
   iii. Make changes in your bashrc file (Local or global)
   Local changes affect only the current user and global changes affect ALL 
   users.
      a. The local rc file is usually in the home folder and named .bashrc 
         (For bash and .cshrc for CSH and TCSH).
      b. The Global rc file is usually in the /etc folder named either as 
         bash.bashrc or bashrc for bash and csh.cshrc or cshrc for CSH or TCSH
	 Add the following lines for BASH:
         alias rm="/path/to/trsh.pl" 
         alias undo="/path/to/trsh.pl -u"

         Add the following lines for CSH/TCSH:
         alias rm "/path/to/trsh.pl" # CSH/TCSH
         alias undo "/path/to/trsh.pl -u" # CSH/TCSH

	 If your shell is not one of these, figure out from your shell's manual on how
	 to make aliases.

3. Trsh sticks to freeDesktop.org's trash specifications. Any non-conformance _is_ a bug. Please
   open a bug in the issues page. 
   Each mounted device other than / or /home will contain its own trash directory and files in 
   those mount points will be moved to their trash directory. 
   
4. Version 2.x of trsh allowed you to specify the trash directory as it was following an ad-hoc 
   specification dreamed up by me. 
   If you have installed trsh 2.x, then please empty the trash or undo all of them. Uninstall 
   trsh by either doing a `make uninstall` or deleting all your trsh directories. 
   (trsh 3.x uses the same alias mechanism and same install path, so those will be overwritten)

4. The mercurial snapshot contains some extra scripts mostly to do with making my life easier in packaging and checkins. 
   (You will not need them unless you want to contribute in the development, for which you will need to ask me first!
    I am more than willing to share my work, but I need to enable the user in googlecode's mercurial repo).
   Along with those, there are some test scripts. these scripts are only present in the mercurial version (If you do an 
   hg clone instead of downloading the tarballs). These test the functionality of trsh so that I do not package 
   a faulty trsh! test-trsh.bash tests trsh on bash. And both are run before a package is created.


REPORTING BUGS
--------------

Report all bugs to:
http://code.google.com/p/trsh/issues

AUTHOR
------

Amithash Prasad {amithash@gmail.com}