gtrash

gtrash is a trash CLI manager that fully complies with the FreeDesktop.org specification.
Unlike rm, gtrash moves files to the system trash can, enabling easy restoration of important files at any time.

If you usually use rm in the shell, gtrash can serve as a substitute.

This tool utilizes the system trash can on Linux, enabling seamless integration with other CLI and desktop applications.

Additionally, gtrash features a modern TUI interface, making it very intuitive to restore any file.

The interface is made with an awesome bubbletea TUI framework.

Table of Contents

• Features
• Supported OS
• Installation
• Usage
• How it works
• FAQ
• Tips
• Configuration
• Related projects

Features

• Intuitive TUI interface for file restoration
  • Allows incremental search for trashed files, enabling the restoration of multiple files simultaneously.
• Full compliance with FreeDesktop.org specification
  • Supports directory size caching, enabling fast size-based filtering and pruning.
• Close compatibility with rm interface
  • Has rm-like mode, You can customize -r, -d behavior
• Multi subcommands design in a single static binary written in Go
• Restoration of co-deleted files together
• Easy integration with other CLI tools, such as fzf
• Safe and Ergonomic
  • Ensures safety by displaying a list and confirmation prompt whenever a file is permanently deleted.

Supported OS

Linux

Supported

Mac

Supported

but Mac's system trash can is not used

Windows

Not supported

It works perfectly on WSL2 because it is real Linux

Installation

From binaries

Download the binary from GitHub Releases and place it in your $PATH.

Install the latest binary to /usr/local/bin:

curl -L "https://github.com/umlx5h/gtrash/releases/latest/download/gtrash_$(uname -s)_$(uname -m).tar.gz" | tar xz
chmod a+x ./gtrash
sudo mv ./gtrash /usr/local/bin/gtrash

AUR (Arch User Repository)

with any AUR helpers

yay -S gtrash-bin
paru -S gtrash-bin

Nixpkgs (NixOS)

nix-env -iA nixpkgs.gtrash

Homebrew (macOS)

brew install umlx5h/tap/gtrash

Go install

go install github.com/umlx5h/gtrash@latest

Build from source

git clone https://github.com/umlx5h/gtrash.git --depth 1
cd gtrash
go build
./gtrash
sudo cp ./gtrash /usr/local/bin/gtrash

Usage

To trash a file, use the put subcommand.
Deleting a directory doesn't require the -r option by default.
(This behavior can be adjusted using --rm-mode.)

$ cd && mkdir dir && touch file1 file2
$ gtrash put dir file1 file2

The summary subcommand provides information about the trash can, displaying item count and total size.
There is a path name, the file has been moved to this path.

$ gtrash summary
[/home/user/.local/share/Trash]
item: 3
size: 4.1 kB

The find subcommand lists the files in the trash.
The Path field shows the original file location, not the one in the trash.

# gtrash f is also acceptable
$ gtrash find
Date                 Path
2024-01-01 00:00:00  /home/user/dir
2024-01-01 00:00:00  /home/user/file1
2024-01-01 00:00:00  /home/user/file2

String queries can be passed as command line arguments for searching files in the trash, using regular expressions by default.

$ gtrash find file1 dir
Date                 Path
2024-01-01 00:00:00  /home/user/dir
2024-01-01 00:00:00  /home/user/file1

There are several ways to restore a file.
To restore with an interactive TUI, use the restore subcommand.

# gtrash r is also acceptable
$ gtrash restore

Within restore, multiple files can be selected for restoration.

The table on the left is the list of files in the trash and the table on the right is the list to be restored.

Press ? for detailed operations.
Navigate using j, k, or the cursor keys.
Use l or right arrow key or Space to move files to the right table.

Vim key bindings are used.
Incremental searches can be performed with /.
Press Enter after selecting files to restore. A list of selected files and a confirmation prompt will appear. Confirm restoration by pressing y.

$ gtrash restore
Date                 Path
2024-01-01 00:00:00  /home/user/dir
2024-01-01 00:00:00  /home/user/file1

Selected 2 trashed files
Are you sure you want to restore? yes/no

There is another type of restoration with TUI.
To restore all the deleted files together in one put command, use the restore-group subcommand.

# gtrash rg is also acceptable
$ gtrash restore-group

In above example, dir1, file1, and file2 can be restored together.
This is useful when many files were deleted together but you want to restore them at once.

For non-TUI restoration, use the --restore option with find.

$ gtrash find file1 dir --restore
Date                 Path
2024-01-01 00:00:00  /home/user/dir
2024-01-01 00:00:00  /home/user/file1

Found 2 trashed files
Are you sure you want to restore? yes/no

To permanently delete files in the trash, use the --rm option with find.
Be aware that this action is irreversible, akin to rm, and the files cannot be restored.

# Delete specific files
$ gtrash find file1 --rm

# Delete all files
$ gtrash find --rm

Help can be viewed with the -h option. Examples are provided for each subcommand.

$ gtrash -h
$ gtrash put -h

How it works

gtrash adheres to the FreeDesktop.org specification.

Its primary function is akin to mv, but it extends functionality by recording meta-information and automatically transferring files to the trash can in the external file system.

Files within the main file system are moved to the following paths in the home directory.

# Standard
$HOME/.local/share/Trash

# If $XDG_DATA_HOME is set
$XDG_DATA_HOME/Trash

The files are moved to the files directory, while metadata is stored in the info directory.

$ gtrash put file1

# Records meta information
$ cat ~/.local/share/Trash/info/file1.trashinfo
[Trash Info]
Path=/home/user/file1
DeletionDate=2024-01-01T00:00:00

# Actual file
$ ls ~/.local/share/Trash/files/file1
/home/user/.local/share/Trash/files/file1

Files within an external file system will be moved to either of the subsequent paths.

# If a .Trash folder already exists, it will be used.
# ($uid folder is created automatically)
# The .Trash directory requires a sticky bit set (can be added using chmod +t)
$MOUNTPOINT/.Trash/$uid

# Used when the above directory is unavailable (typically used)
$MOUNTPOINT/.Trash-$uid

To use the first directory, create a .Trash directory in advance:

# You can check with the df command
$ cd $MOUNTPOINT

$ mkdir .Trash
$ chmod a+rw .Trash

# Set the sticky bit
$ chmod +t .Trash

$MOUNTPOINT is the same as the information displayed in the df command.

# Mounted on
$ df foo
Filesystem Size  Used Avail Use% Mounted on
/dev/sda   54G   48G  3.6G  93% /

The mv command copies and deletes files when moving across file systems.
This process consumes more time and increases disk usage on the destination file system.

The inability to use the rename(2) syscall across different file systems necessitates this behavior.

For this reason, gtrash attempts to move files to the trash can within the same file system whenever possible.
You can also configure it to always use the trash can in the $HOME directory.

Refer to the Configuration for further details.

The summary subcommand lists paths to all trash cans:

$ gtrash summary

Using the --show-trashpath option with the find command displays the real path for each trashed file.

$ gtrash find --show-trashpath

For detailed behavior insights, run the command with the --debug option to view internal processes.

FAQ

What's the difference between this command and the rm command?

While rm uses the unlink syscall, rendering file deletion irreversible, gtrash moves files using the rename syscall, enabling restoration.

gtrash aims to mirror the rm interface but ignores -r, -R, --recursive, and -d by default.

$ gtrash put -h
Flags:
  -d, --dir               ignored unless --rm-mode set
  -f, --force             ignore nonexistent files and arguments
  -i, --interactive       prompt before every removal
  -I, --interactive-once  prompt once before trashing
  -r, -R, --recursive     ignored unless --rm-mode set
      --rm-mode           enable rm-like mode (change behavior -r, -R, -d)
  -v, --verbose           explain what is being done

The -r option is not necessary for deleting folders since files are restorable even if mistakenly removed.

However, some users may prefer the rm behavior. In such cases, enable the above option with --rm-mode. (Although it is not completely compatible.)

# To delete a folder, -r or -d is required.
$ gtrash put --rm-mode dir1/
gtrash: cannot trash "dir1/": Is a directory

$ gtrash put --rm-mode -r dir1/

This behavior can be set using an environment variable or an alias, whichever suits your preference.

# Same as --rm-mode
$ GTRASH_PUT_RM_MODE="true" gtrash put -r dir/

# Alias is also possible
$ alias gtrash-put="gtrash put --rm-mode"

What are the advantages of