RTRASH(1)

NAME
rtrash - fast freedesktop.org trash tool with an rm-compatible interface

SYNOPSIS
rtrash [COMMAND] [ARGS]...

rtrash [OPTION]... [FILE]...

Multi-call names (symlinks to the same binary): trash-put, trash, trash-empty, trash-list, trash-restore, trash-rm, and optionally rm (put into trash).

DESCRIPTION
rtrash implements the freedesktop.org Trash specification on Linux: home trash ($XDG_DATA_HOME/Trash) and per-volume trash directories, with atomic .trashinfo files. It provides an rm-compatible put path and a trash-cli-style suite (list, restore, empty, selective permanent delete).

Invoked as rtrash with a known subcommand, that command runs. Invoked as rtrash with no subcommand (or as rm, trash, or trash-put), arguments are treated as put (move into the trash). The multi-call name trash-rm is permanent delete of matching trash entries , not the same as multi-call rm (which puts).

GLOBAL OPTIONS
When rtrash is invoked with no subcommand yet recognized:

-h, --help
    Display help and exit.

-V, --version
    Output version information and exit.

COMMANDS

  put
rtrash put [OPTION]... [FILE]...

Also: trash-put, trash, rm (multi-call), or bare rtrash with paths/flags.

Move FILE s into the trash. Accepts common rm(1) flags with the same interactive/force semantics; nothing is unlinked permanently.

-f, --force
    Ignore nonexistent files and arguments, never prompt.

-i  Prompt before every removal.

-I  Prompt once before removing more than three files, or when removing recursively.

--interactive[=WHEN]
    Prompt according to WHEN: never, once (-I), or always (-i); without WHEN, prompt always.

-r, -R, --recursive
    Remove directories and their contents (into the trash).

-d, --dir
    Remove empty directories.

-v, --verbose
    Explain what is being done.

--one-file-system
    Accepted for rm compatibility (no-op: entries are moved whole, never traversed like rm -x).

--preserve-root
    Do not remove ‘/’ (default).

--no-preserve-root
    Do not treat ‘/’ specially.

--help
    Display help and exit.

--version
    Output version information and exit.

  empty
rtrash empty [OPTION]... [DAYS]

Also multi-call trash-empty.

Purge trashed items. With DAYS, only items trashed more than DAYS days ago.

-n, --dry-run
    Report what would be removed without removing anything; also prints approximate reclaimable disk space.

-v, --verbose
    Print each removed item.

-f, --force
    Accepted for trash-cli compatibility (emptying never prompts).

--trash-dir=PATH
    Empty only this trash directory (repeatable); default is the home trash plus every mounted volume.

--home-only
    Only the home trash (skip volume trash discovery).

--help
    Display help and exit.

--version
    Output version information and exit.

  list
rtrash list [OPTION]...

Also multi-call trash-list.

List trashed items as ‘DELETION-DATE ORIGINAL-PATH’, oldest first.

--home-only
    Only the home trash ($XDG_DATA_HOME/Trash).

--trash-dir=PATH
    List only this trash directory (repeatable); default is the home trash plus every mounted volume.

--help
    Display help and exit.

--version
    Output version information and exit.

  status
rtrash status [OPTION]...

Summarize discovered trash: item count and approximate reclaimable size (per root and total). Uses the same disk-usage walk as empty --dry-run.

--home-only
    Only the home trash ($XDG_DATA_HOME/Trash).

--trash-dir=PATH
    Only this trash directory (repeatable).

--help
    Display help and exit.

--version
    Output version information and exit.

  restore
rtrash restore [OPTION]... [PATH]

Also multi-call trash-restore.

Restore a trashed item to its original location. With PATH, restore the item originally at PATH; without, choose among items trashed from under the current directory. A single match restores directly; multiple matches are listed for interactive selection.

-f, --force
    Overwrite an existing file at the original location.

--home-only
    Only the home trash (skip volume trash).

--trash-dir=PATH
    Only consider this trash directory (repeatable).

--help
    Display help and exit.

--version
    Output version information and exit.

  setup
rtrash setup [OPTION]...

Install multi-call symlinks, bash/zsh completions, and this man page under a user prefix (default ~/.local, or $PREFIX if set). Assets are embedded in the binary so a cargo install user does not need a source checkout. Preferred post-install step: rtrash setup.

--prefix=DIR
    Install root (default: ~/.local).

--bin-dir=DIR
    Override the directory for multi-call symlinks (default: PREFIX/bin).

--with-rm
    Also link rm → rtrash (put into trash).

-n, --dry-run
    Print actions without writing.

-f, --force
    Replace existing links/files (use after upgrades).

-v, --verbose
    Print each path written.

  completions
rtrash completions {bash|zsh}

Print the embedded completion script to stdout (packagers / custom paths).

  man
rtrash man

Print the embedded man page source to stdout.

  rm (permanent delete from trash)
rtrash rm [OPTION]... PATTERN

Also multi-call trash-rm.

Permanently remove trashed items whose original path or basename matches a PATTERN (shell-style glob; quote globs from the shell). Matching entries are deleted from the trash (files/ and .trashinfo), not restored.

Note: multi-call name rm means put into trash (safe). This command (subcommand rtrash rm or multi-call trash-rm) permanently deletes matching trash entries — not a synonym for put.

--trash-dir=PATH
    Only consider this trash directory (repeatable).

--home-only
    Only the home trash (skip volume trash).

-n, --dry-run
    List matches and reclaimable size; do not delete.

-f, --force
    Allow mass patterns that match everything (e.g. ‘*’).

-v, --verbose
    Print each permanently removed original path.

--help
    Display help and exit.

--version
    Output version information and exit.

Examples:
    rtrash rm '*.o'
    rtrash rm -n '*.o'
    trash-rm foo

ENVIRONMENT

XDG_DATA_HOME
    Base for the home trash directory ($XDG_DATA_HOME/Trash). Defaults under ~/.local/share when unset.

HOME
    Used when resolving the default data home.

FILES

$XDG_DATA_HOME/Trash
    Home trash: files/, info/, directorysizes, and optional lock file.

$top/.Trash/$uid
    or $top/.Trash-$uid Per-volume trash on other mounts (see the Trash specification).

EXIT STATUS

0   Success.

1   Failure (e.g. could not trash or purge an item).

2   Usage error.

Put mode mirrors common rm(1) exit conventions.

SEE ALSO
rm(1), Trash specification: https://specifications.freedesktop.org/trash-spec/trashspec-latest.html

Shell completions ship in the source tree under completions/ (bash and zsh). See the project README for install paths.

AUTHOR
Written for the rtrash project.

COPYRIGHT
MIT License. See the LICENSE file in the distribution.