trash-cli

A command line interface to the freedesktop.org trashcan. It trashes files recording the original path, deletion date, and permissions. It uses the same trashcan used by KDE, GNOME, and XFCE.

Installation

# Via Homebrew (Linux/macOS)
brew install trash-cli

# Via pip
pip install trash-cli

# Via apt (Debian/Ubuntu)
sudo apt install trash-cli

# Via pacman (Arch Linux)
sudo pacman -S trash-cli

# Via dnf (Fedora)
sudo dnf install trash-cli

Commands Overview

trash-put

Move files or directories to the trash can.

trash-put <file>           # Trash a file
trash-put <dir>/           # Trash a directory
trash-put -f <file>        # Silently ignore nonexistent files
trash-put -v <file>        # Verbose output

Options

• -f, --force - Silently ignore nonexistent files
• -v, --verbose - Explain what is being done
• --trash-dir TRASHDIR - Use TRASHDIR as trash folder

Notes

• Unlike rm, trash-put does not require -R for directories
• Files trashed from home partition go to ~/.local/share/Trash/
• Files from other partitions go to $partition/.Trash/$uid or $partition/.Trash-$uid

trash-list

List all trashed files.

trash-list                          # List all trashed files
trash-list | grep <pattern>         # Search for specific files
trash-list --all-users              # List trashcans of all users

Output Format

2008-06-01 10:30:48 /home/user/bar
2008-06-02 21:50:41 /home/user/baz

Format: deletion_date original_path

trash-restore

Restore trashed files to their original location.

trash-restore                       # Interactive restore
trash-restore --overwrite          # Overwrite existing files
trash-restore --sort date          # Sort by date (default)
trash-restore --sort path          # Sort by path

Interactive Mode

$ trash-restore
0 2007-08-30 12:36:00 /home/andrea/foo
1 2007-08-30 12:39:41 /home/andrea/bar
2 2007-08-30 12:39:41 /home/andrea/baz
What file to restore [0..2]: 0

• Enter the number to restore that file
• Use 0-2,3 to restore multiple files
• Use --overwrite to replace existing files

trash-empty

Permanently remove files from trash.

trash-empty                 # Remove ALL trashed files
trash-empty 7              # Remove files older than 7 days
trash-empty 1              # Remove files older than 1 day

Examples

# Delete everything in trash
trash-empty

# Keep only files from the last 7 days
trash-empty 7

# Keep only today's files
trash-empty 1

trash-rm

Remove specific files from trash (by pattern).

trash-rm <pattern>         # Remove files matching pattern
trash-rm '*.o'             # Remove all .o files
trash-rm foo               # Remove all files named "foo"
trash-rm /full/path        # Remove by original path

Note: Use quotes to protect pattern from shell expansion.

trash-rm '*.log'          # Correct
trash-rm *.log            # Wrong - shell will expand

Safety Tips

Replace rm with trash-put

Add to .bashrc or .zshrc:

# Remind yourself not to use rm directly
alias rm='echo "Use trash-put instead!"; false'

# Or use a safer alias
alias rm='trash-put'

To bypass the alias when you really need rm:

\rm file.txt

Recovery Workflow

1. Check what's in trash: trash-list
2. Find your file: trash-list | grep <filename>
3. Restore: trash-restore

Trash Location

• Home partition: ~/.local/share/Trash/
• Other partitions: $mount_point/.Trash/$uid or $mount_point/.Trash-$uid

Limitations

• Does not support BRTFS volumes
• Cannot trash files from read-only filesystems

FAQ

Creating a top-level .Trash directory

If you need to create a trash directory on a different partition:

sudo mkdir --parent /.Trash
sudo chmod a+rw /.Trash
sudo chmod +t /.Trash

Should I alias rm to trash-put?

The author advises against this. Although trash-put seems compatible with rm, it has different semantics that will cause problems. For example, while rm requires -R for deleting directories, trash-put does not.

Instead, use a warning alias:

alias rm='echo "This is not the command you are looking for."; false'

To bypass when you really need rm:

\rm file.txt

See Also

• Official GitHub
• FreeDesktop.org Trash Spec