gomi

🗑️ A Safer Alternative to the UNIX rm Command!

gomi (meaning "trash" in Japanese) is a simple CLI tool written in Go that adds trash can functionality to the command line.

In a typical CLI, there’s no "trash" folder like in graphical file managers. This means if you accidentally delete important files using the rm command, restoring them can be very difficult. That's where gomi comes in. Unlike rm, which permanently deletes files, gomi moves them to the trash, allowing you to easily restore files whenever necessary. If you’re used to rm in the shell, gomi works as a more convenient, safer alternative.

Features

• 🔄 Familiar syntax - works just like rm command but with a safety net
• 🎯 XDG Trash spec compliant - integrates perfectly with your desktop environment
• 👀 Beautiful TUI for browsing and restoring deleted files
• ⚡️ Blazing fast with concurrent operations
• 🖥️ Cross-platform support (Linux, macOS, Windows)
• 🎨 Syntax highlighting for previewing trashed files
• 🔍 Powerful search and filtering capabilities
• 💽 Multi-Volume Support - Handle file deletions across multiple mount points effortlessly
• ⚙️ Rich Configuration - Customize everything from file filters and color schemes to preview options and UI density

For detailed information about gomi's architecture and design decisions, see architecture.md.

Usage

gomi is compatible with rm flags (like -i, -f, and -r), so you can easily replace rm by setting up an alias:

alias rm=gomi

I developed gomi as a safer replacement for rm, so setting up the alias is recommended. However, feel free to adjust to your preferences. The instructions below assume the alias is set.

Move files to the trash:

rm files

Restore a file to its original location. The --restore flag is a bit long, so you can use the shorthand -b:

rm -b

This launches an interactive file browser where you can:

• Navigate through trashed files using arrow keys
• Press / to start searching/filtering files by name
• Press Tab to select multiple files for restoration
• Press Space to preview file contents
• Press Enter to restore selected files

Installation

Getting Started in Seconds

Get started with gomi in just one command:

curl -fsSL https://gomi.dev/install | bash

To install it in a specific directory (e.g., ~/.local/bin):

curl -fsSL https://gomi.dev/install | PREFIX=~/.local/bin bash

From Prebuilt Binaries

Download the latest precompiled binary from GitHub Releases and place it in a directory included in your $PATH.

Using a CLI package manager

Using afx

Write a YAML manifest, then run the install command.

github:
- name: babarot/gomi
  description: Trash can in CLI
  owner: babarot
  repo: gomi
  release:
    name: gomi
    tag: v1.6.2
  command:
    link:
    - from: gomi
    alias:
      rm: gomi

afx install

Using Homebrew

brew install gomi

Using Scoop

scoop bucket add babarot https://github.com/babarot/scoop-bucket
scoop install gomi

Using AUR

You can install gomi using an AUR helper:

yay -S gomi

paru -S gomi

Find it on AUR.

Configuration

You can customize gomi's behavior and appearance with a YAML configuration file. The first time you run gomi, a default config will be automatically generated at ~/.config/gomi/config.yaml.

Here is an example of the default config:

# Controls the core functionality of gomi's trash operations.
# Includes settings for trash directory strategy (XDG or legacy),
# restoration behavior, and permanent deletion features.
# These settings directly affect how files are handled.
core:
  trash:
    strategy: auto      # or "xdg" or "legacy"
                        # Strategy determines which trash specification to use.

    gomi_dir: ~/.gomi   # Path to store trashed files. Can be changed to another location.
                        # Supports environment variable expansion like $HOME or ~.
                        # If empty, defaults to ~/.gomi.
                        # This config is only available on "legacy", "auto" trash strategy

    home_fallback: true # If true, fallbacks to home trash when external trash fails

    forbidden_paths:    # List of paths that cannot be moved to trash for safety
      - "$HOME/.local/share/Trash"
      - "$HOME/.trash"
      - "$XDG_DATA_HOME/Trash"
      - "/tmp/Trash"
      - "/var/tmp/Trash"
      - "$HOME/.gomi"
      - "/"
      - "/etc"
      - "/usr"
      - "/var"
      - "/bin"
      - "/sbin"
      - "/lib"
      - "/lib64"

  restore:
    confirm: false      # If true, prompts for confirmation before restoring (yes/no)
    verbose: true       # If true, displays detailed restoration information

  permanent_delete:
    enable: false       # If true, enables permanent deletion of files from trash.
                        # When enabled, files can be deleted permanently using the 'D' key.
                        # This operation is irreversible and bypasses the trash.
                        # Default is false for safety.

# Customizes the interactive interface used during file restoration.
# Provides detailed customization of colors, layouts, and preview features.
# Controls how files and directories are displayed in both list and detail views.
ui:
  density: spacious # or compact
  preview:
    syntax_highlight: true
    colorscheme: nord  # Available themes: https://xyproto.github.io/splash/docs/index.html
    directory_command: ls -F -A --color=always
  style:
    list_view:
      cursor: "#AD58B4"         # purple - color of the cursor border and text
      selected: "#5FB458"       # green - color of selected files
      filter_match: "#F39C12"   # orange - color of matched text when searching
      filter_prompt: "#7AA2F7"  # blue - color of the "Filter:" prompt text
      indent_on_select: false
    detail_view:
      border: "#FFFFFF"
      info_pane:
        deleted_from:
          fg: "#EEEEEE"
          bg: "#1C1C1C"
        deleted_at:
          fg: "#EEEEEE"
          bg: "#1C1C1C"
      preview_pane:
        border: "#3C3C3C"
        size:
          fg: "#EEEEDD"
          bg: "#3C3C3C"
        scroll:
          fg: "#EEEEDD"
          bg: "#3C3C3C"
    deletion_dialog: "#FF007F" # pink
  exit_message: bye!   # Customizable exit message
  paginator_type: dots # or arabic

# Configures which files appear in the restoration list.
# Note: While all trash operations are recorded in history,
# these settings only control file visibility when browsing the trash (`gomi -b`).
# Provides filtering options by age, patterns, size, etc.,
# to help manage large trash directories.
history:
  include:
    within_days: 100 # Only show files deleted in the last 100 days
  exclude:
    files:
    - .DS_Store      # Exclude .DS_Store files
    patterns:
    - "^go\\..*"     # Exclude files starting with "go."
    globs:
    - "*.jpg"        # Exclude JPEG files
    size:
      min: 0KB       # Exclude empty files
      max: 10GB      # Exclude files larger than 10GB

# Enables debugging and operation logging for gomi.
# When enabled, records all operations including file movements,
# restorations, and encountered errors.
# Includes rotation settings to manage log file sizes and retention.
logging:
  enabled: false     # Enable/disable logging
  level: info        # Available levels: debug, info, warn, error
  rotation:
    max_size: 10MB   # Maximum size of each log file
    max_files: 3     # Number of old log files to retain

Pruning Trash Files

The --prune option allows you to manage your trash contents by permanently removing files based on various criteria.

Basic Usage

gomi --prune=<argument>

Use Cases

1. Remove Orphaned Metadata Files

Orphaned metadata refers to .trashinfo files that have lost their corresponding data files in the trash. In the XDG trash specification, each trashed file has two components:

• The actual file data (stored in files/)
• A metadata file (stored in info/ with .trashinfo extension) containing information about when and where the file was deleted from

When the data file is lost but the metadata file remains, it becomes "orphaned". This can happen due to:

• Manual deletion of files from the trash
• System crashes during trash operations
• Disk errors or file system corruption

To clean up these orphaned metadata files:

gomi --prune=orphans

This command identifies and removes orphaned .trashinfo files to maintain trash consistency.

2. Remove Files Older Than Specified Duration

Remove files that were moved to trash before the specified duration:

gomi --prune=1y     # Remove files older than 1 year
gomi --prune=6m     # Remove files older than 6 months
gomi --prune=30d    # Remove files older than 30 days
gomi --prune=1w     # Remove files older than 1 week

3. Remove Files Within a Time Range

Remove files that were moved to trash within a specific time range:

gomi --prune=2m,3m  # Remove files trashed between 2 and 3 months ago
gomi --prune=0d,1d  # Remove files trashed today (0-1 day ago)
gomi --prune=1w,2w  # Remove files trashed between 1 and 2 weeks ago

Duration Format

The following duration units are supported:

• h, hour, hours (hours)
• d, day, days (days)
• w, week, weeks (weeks)
• m, month, months (months)
• y, year, years (years)

Additional Notes

• Arguments can be specified with either commas or separate --prune flags:

  gomi --prune=1d,7d          # Using comma
  gomi --prune=1d --prune=7d  # Using multiple flags (same result)
  

• When more than two durations are specified, gomi uses the shortest and longest durations as the range:

  gomi --prune=0d,1d,3d   # Treats as 0d,3d (today to 3 days ago)
  gomi --prune=2w,3d,1m   # Treats as 3d,1m (3 days to 1 month ago)
  

  The order of arguments doesn't matter - gomi will always use the most recent (shortest duration) and oldest (longest duration) as the time range boundaries.

• The orphans argument cannot be combined with duration arguments.

• This operation permanently deletes files and cannot be undone. Double confirmation will be required before deletion.

Debugging

Gain deeper insights into gomi's operations by using the --debug flag:

# Show existing log file content
gomi --debug

# Follow new log entries in real-time (requires logging enabled)
gomi --debug=live

The --debug flag has two modes:

• Full-view mode (without =live, or with =full)
  • Shows the entire content of the existing log file.
• Live-view mode (with =live)
  • Follows and displays new log entries in real-time, similar to tail -f.
  • While running gomi --debug=live, you can open another terminal and execute gomi commands to monitor live log updates.
  • This feature is invaluable for troubleshooting and tracking gomi's actions in real-time.

[!NOTE] To use any debug features, logging must be enabled in the configuration file. The --debug flag only displays logs; it does not enable logging by itself.

logging:
  enabled: true # Enable logging functionality

Related

CLI Trash Tools

• andreafrancia/trash-cli
• sindresorhus/trash

Editor Integration

• babarot/rm.nvim - Neovim plugin for safe file deletion with gomi support

License

MIT