go2trash

README

go2trash

Cross-platform OS trash integration for Go. Moves files to the native operating system trash/recycle bin so users can restore them later, instead of permanently deleting with os.Remove.

Platform Support

Platform	Implementation
Linux	FreeDesktop.org Trash Specification 1.0
macOS	NSFileManager.trashItem (macOS 10.8+)
Windows	SHFileOperationW via golang.org/x/sys/windows

Installation

go get github.com/rafshawn/go2trash

Usage

package main

import (
    "log"

    go2trash "github.com/rafshawn/go2trash"
)

func main() {
    err := go2trash.MoveToTrash("/path/to/file.txt")
    if err != nil {
        log.Fatal(err)
    }
}

Overview

Linux

Trashed files are sent to user's (or root's) trash (~/.local/share/Trash/), following the FreeDesktop.org Trash Specification[^1]. A .trashinfo file is created with the original path and deletion timestamp.

~/.local/share/Trash/
    files/
        file.txt
    info/
        file.txt.trashinfo

The .trashinfo file contains metadata to allow file restoration:

[Trash Info]
Path=/absolute/path/to/file.txt
DeletionDate=20060102T03:04:05

macOS

[!IMPORTANT] macOS builds require a Mac due to CGO and the Objective-C SDK dependency.

File operations are entirely handled by NSFileManager through CGO and Objective-C. The trashItemAtURL method moves files to the Trash without showing security prompts, and supports the Finder "Put Back" feature. GO just waits for a return 0 on success or a return -1 on failure.

This means:

• The file appears in Finder's Trash with full "Put Back" support
• No security prompts ("App would like to control Finder")
• No osascript/AppleScript subprocess (native performance)
• Works in headless environments

Windows

The Windows implementation uses SHFileOperationW from Shell32.dll via golang.org/x/sys/windows to send files to the Recycle Bin. It is a pure syscall implementation (no CGO or MinGW is dependency required).

The FOF_ALLOWUNDO flag enables trash functionality, while additional flags suppress confirmation dialogs and progress UI for silent operation.

API

func MoveToTrash(filePath string) error

MoveToTrash sends a file or directory to the OS trash. Returns an error if the file does not exist or the operation fails.

Testing

Run tests locally:

go test -v ./...

The project includes GitHub Actions that run tests on macOS, Linux, and Windows on every push and pull request.

License

MIT License. See LICENCE for details.

Resources

• Calling C from Go (Eric Chiang)

Documentation

Overview

Package go2trash provides cross-platform OS trash integration for Go.

It moves files to the native operating system trash/recycle bin so that users can restore them later, instead of permanently deleting with os.Remove.

Platform Support

## macOS Uses NSFileManager.trashItemAtURL (native Cocoa API via CGO). Supports Finder "Put Back" functionality. No security prompts required.

## Linux Follows the FreeDesktop.org Trash Specification 1.0. Files appear in GNOME Files, Dolphin, and other compliant file managers. Creates .trashinfo metadata files for recovery.

## Windows Uses SHFileOperationW via golang.org/x/sys/windows. Pure syscall implementation with no CGO dependency. Sends files to the Recycle Bin with no confirmation dialogs shown.

Basic Usage

err := go2trash.MoveToTrash("/path/to/file.txt")
if err != nil {
    log.Fatal(err)
}

Index

• MoveToTrash -- sends a file or directory to the OS trash

Testing

Run tests with: go test -v ./...

Cross-platform CI runs tests on macOS, Linux, and Windows via GitHub Actions.

Index

• func MoveToTrash(filePath string) error

Functions

func MoveToTrash

func MoveToTrash(filePath string) error

MoveToTrash sends a file or directory to the FreeDesktop.org Trash.

Creates a .trashinfo metadata file alongside the trashed file to display and restore the file.