Metadata-Version: 2.4
Name: rmsafe
Version: 1.0.0
Summary: Safe trash management utilities and CLI.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: COPYING
Requires-Dist: typer
Requires-Dist: rich
Requires-Dist: jsoncomment
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# rmsafe

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

## Installation

### Homebrew (macOS/Linux)

```bash
brew tap leftrk/rmsafe
brew install rmsafe
```

### pip

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

### uv

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

### Development

```bash
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

```bash
# 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.):

```bash
alias rm='rmsafe trash'
```

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

### Commands

```bash
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.

```bash
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.

```bash
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.

```bash
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.

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

### empty

Empty trash (with confirmation).

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

### status

Show trash statistics.

```bash
rmsafe status
```

Output shows:
- Total file count
- Total size
- Trash location
- Auto-clean settings

### Global Options

All commands support these options:

```bash
--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):

```jsonc
{
  "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
