rmsafe 1.0.0

Safe trash management utilities and CLI.

rmsafe

A modern rm replacement that moves files to trash instead of permanently deleting them. Works on macOS and Linux.

Installation

Homebrew (macOS/Linux)

brew tap leftrk/rmsafe
brew install rmsafe

pip

pip install git+https://github.com/leftrk/rmsafe.git

uv

uv tool install git+https://github.com/leftrk/rmsafe.git

Development

git clone https://github.com/leftrk/rmsafe.git
cd rmsafe

# Using uv (recommended)
uv sync --dev
uv run rmsafe --help

# Using pip
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=rmsafe

# Run specific test file
uv run pytest tests/test_commands_trash.py

# Run specific test
uv run pytest tests/test_commands_trash.py::test_trash_file

Usage

Replace rm (recommended)

Add to your shell config (~/.bashrc, ~/.zshrc, etc.):

alias rm='rmsafe trash'

Now rm file.txt moves to trash instead of deleting forever.

Commands

rmsafe trash <files>      # Move files to trash
rmsafe restore <pattern>  # Restore trashed files
rmsafe list [pattern]     # List trashed files
rmsafe undo [n]           # Undo recent deletions
rmsafe empty [days]       # Empty trash
rmsafe status             # Show trash status

trash

Move files to trash. Supports multiple files, directories, and glob patterns.

rmsafe trash file.txt
rmsafe trash *.log
rmsafe trash dir/
rmsafe trash file.txt --dry-run    # Preview without action
rmsafe trash file.txt --verbose    # Show details
rmsafe trash file.txt --no-confirm # Skip confirmation

restore

Restore trashed files back to their original locations.

rmsafe restore            # Interactive selection
rmsafe restore file.txt   # Restore by name
rmsafe restore *.log      # Restore by pattern
rmsafe restore --to ~/backup/  # Restore to different location

list

List files in trash with size and deletion date.

rmsafe list
rmsafe list *.log
rmsafe list --sort size   # Sort by size
rmsafe list --sort time   # Sort by deletion time (default)

undo

Undo recent trash operations from history.

rmsafe undo        # Undo last deletion
rmsafe undo 3      # Undo last 3 deletions
rmsafe undo --list # Show undo history

empty

Empty trash (with confirmation).

rmsafe empty           # Empty all trash
rmsafe empty 7         # Empty files older than 7 days
rmsafe empty --force   # Skip confirmation

status

Show trash statistics.

rmsafe status

Output shows:

• Total file count
• Total size
• Trash location
• Auto-clean settings

Global Options

All commands support these options:

--dry-run       Preview without executing
--verbose       Show detailed output
--color MODE    Color output: always, never, auto (default: auto)
--config PATH   Use custom config file
--confirm-large SIZE  Set threshold for large file confirmation
--no-confirm    Skip all confirmation prompts

Configuration

Config file: ~/.config/rmsafe/config.jsonc

Default config (JSONC format with comments):

{
  "trash": {
    "max_size": "500MB",        // Maximum trash size
    "location": null,           // Custom trash path (null = system default)
    "auto_clean_days": 30       // Auto-delete after N days
  },
  "behavior": {
    "confirm_large_files": "10MB",  // Prompt for files > this size
    "confirm_directories": true,    // Prompt before trashing directories
    "undo_history_limit": 100       // Max undo history entries
  },
  "output": {
    "color": "auto",            // Color mode: always, never, auto
    "verbose": true,            // Show detailed messages
    "icons": true,              // Use emoji icons
    "table_format": "rounded"   // Table style for list output
  },
  "btrfs": {
    "enable_clone": true,       // Use Btrfs clone (Linux only)
    "fallback_on_error": true   // Fall back to copy on clone failure
  }
}

Platform Support

Platform	Trash Location
macOS	~/.Trash
Linux	~/.local/share/Trash/files/ + info/

Btrfs Support (Linux)

On Btrfs filesystems, rmsafe uses reflink clone for zero-copy moves. Falls back to regular copy if clone fails.

Comparison with trash-cli

Feature	rmsafe	trash-cli
CLI Framework	Typer (modern)	argparse
Output	Rich tables/colors	Plain text
Config format	JSONC (comments allowed)	INI
Undo history	Built-in history tracker	Limited
Btrfs support	Native reflink clone	No
macOS integration	Uses Finder's .Trash	Separate directory
Confirmation UX	Timeout prompts for large files	Basic confirmations
Size formatting	Human-readable (KB/MB/GB)	Bytes only
Pattern matching	Glob patterns in restore	Limited

Key Advantages over trash-cli

1. Modern CLI: Rich output with colored tables and icons
2. Undo history: Track and undo recent deletions with history
3. Btrfs optimization: Zero-copy moves on Btrfs filesystems via reflink
4. JSONC config: Comments and trailing commas supported
5. Smart confirmations: Timeout-based prompts for large files (won't hang scripts)
6. macOS native: Uses Finder's trash directory directly

Differences from rm

Feature	rm	rmsafe
Default behavior	Delete forever	Move to trash
Recovery	No	Yes (restore, undo)
Confirmation	-i only	Always for directories, large files
Progress	No	Rich table output
History	No	Undo history

License

MIT