[Plugins] Working with the system trash using the Lua API

[drewlwhitney]

Describe the question

There looks to be an fs.trash API with methods like fs.trash.empty(), fs.trash.restore(), etc.

Is this API available for user plugins? Is so, are there any examples of using fs.trash.restore() specifically? I was looking at plugins/trash.lua but I didn't really understand the data type of ent on line 62.

Additionally, if you have the path to a file, how to you send it to the trash from Lua? I was trying something like ya emit trash [PATH] but that doesn't seem to work.

If the API is not for plugins, then is the best way to manage the trash just trash-cli?

Thanks!

Checklist

• I have read all the documentation
• I have searched the existing discussions/issues

[hippi345]

it's reachable from any plugin (fs.trash is just a field on fs), but heads up it's only on main/nightly right now and isn't documented, so it could still change.

ent there is a TrashEntry userdata. you don't build it yourself, you get one from fs.trash.list() or fs.trash.entry{ top = ..., rel = ... }. it has key, top, rel, name, original (where it came from), stat, etc. restore takes a list of them:

local ents, err = fs.trash.list() -- top level of the trash
for _, ent in ipairs(ents or {}) do
  if ent.original and tostring(ent.original) == "/home/me/notes.txt" then
    local ok, err = fs.trash.restore { ent }
  end
end

(these are async, so call them from an async plugin context, not a sync one)

for sending a path to the trash there's no fs.trash.put or anything. the remove action doesn't take a path, it works on the selection or the hovered file, so ya emit trash PATH won't do anything. you can reveal the file first and then emit remove with hovered = true, or just shell out with Command("trash-put") / gio trash. for a plugin the shell-out is the least fiddly

[drewlwhitney]

Gotcha! I implemented essentially this in my plugin. I will probably need to use trash-cli anyway though; the fs.trash.restore() API is a little finicky. It freaks out if you delete two files with the same name, then use this method to restore one of them. You get restore target already exists even though it doesn't, but the file does get restored anyway.

I also can't tell if the order on fs.trash.list() is random or not.

Thanks!

[hippi345]

ah that's on my snippet, sorry. the loop doesn't stop after the first match, so if two trashed files came from the same path it restores the first one, then tries the second and runs into the file it just put back. that's your restore target already exists. just break (or return) right after the restore.

and list() isn't sorted, it's just read_dir order of the trash's info folder, so basically whatever the filesystem hands back. sort it yourself if you need an order

[drewlwhitney]

Oh I didn't even clock that. I was restoring multiple files at once, but the way I implemented the algorithm had this same problem. It works now. Thanks!

[pballada]

Is fs.trash available to plugins? Yes. It's part of the same global fs table every plugin sees, and it ships in v26.9.1 (yazi-fs/src/trash/lua.rs). It isn't in the plugin docs yet, though, so treat it as an internal API that could change. All of its functions are async, so call them from your plugin's async entry, not inside ya.sync. Like the rest of fs, they return value on success or nil, err on failure (true / false, err for actions).

Function	What it does
fs.trash.list()	Top-level items in the trash, as a table of entries
fs.trash.list(ent)	Children of a trashed directory
fs.trash.entry { top = …, rel = … }	Look up one entry by its id
fs.trash.restore { ent1, ent2, … }	Restore entries to their original location
fs.trash.remove("file" | "dir", ent)	Permanently delete one entry
fs.trash.rename(ent, path), fs.trash.metadata(ent, follow), fs.trash.empty()	Rename, stat, empty the whole trash

What ent is: a TrashEntry userdata. You get one from fs.trash.list() or fs.trash.entry{…}. Its fields are key, name, top, rel (together these identify it), original (where it was deleted from), stat, lstat, link_to and backing (where it actually sits in the trash).

Restore a file by its original path:

return {
	entry = function(_, job)
		local target = job.args[1] -- e.g. "/home/me/notes/todo.md"
		local ents, err = fs.trash.list()
		if not ents then
			return ya.notify { title = "Trash", content = tostring(err), timeout = 5, level = "error" }
		end
		for _, ent in ipairs(ents) do
			if ent.original and tostring(ent.original) == target then
				local ok, err = fs.trash.restore { ent }
				if not ok then
					ya.notify { title = "Trash", content = "Restore failed: " .. tostring(err), timeout = 5, level = "error" }
				end
				return
			end
		end
	end,
}

If the destination already exists, restore fails with err.kind == "AlreadyExists". The preset trash.lua handles that case for directories by restoring child by child (restore_recursively).

Sending a path to the trash: there's no fs.trash.put, and trash isn't an action, which is why ya emit trash … does nothing. Moving to trash goes through the remove action, which only acts on the selection or the hovered file. It accepts force, permanently and hovered, but not a path. So either reveal the file first and then remove it:

ya.emit("reveal", { Url(path) })
ya.emit("remove", { force = true, hovered = true }) -- no `permanently`, so it goes to the trash

or, if you don't want to move the cursor, call an external tool with Command("trash-put"):arg(path):status() (trash-cli) or gio trash on Linux. On macOS, the trash command from Homebrew does the same.