rmw.1

.nh
.TH RMW 1 "July 2026" "rmw 0.10.0" "User Commands"

.SH NAME
rmw \- safe-remove utility for the command line


.SH SYNOPSIS
\fBrmw\fP [\fIOPTION\fP]... \fIFILE\fP\&...

.PP
Move FILE(s) to the trash

.PP
\fBrmw\fP \fB-s\fR

.PP
\fBrmw\fP \fB-u\fR

.PP
\fBrmw\fP \fB-z\fR \fIFILE\fP\&...

.PP
Restore FILE(s) from the trash


.SH DESCRIPTION
rmw (ReMove to Waste) is a safe-remove and restore utility for the command
line. By default it uses your desktop's trash (the FreeDesktop.org Trash
specification) and needs no setup, though you can add your own waste folders.
It can also purge items after a set number of days.


.SH OPTIONS
.TP
\fB-h\fR, \fB--help\fR
show help for command line options

.TP
\fB-c\fR, \fB--config\fR \fIFILE\fP
use an alternate configuration

.TP
\fB-l\fR, \fB--list\fR
list waste directories, one path per line

Add \fB-v\fR to also show each folder's attributes (such as "no-add")
and a list of candidate trash locations that rmw would create on other
file systems when needed.

.TP
\fB-g[N_DAYS]\fR, \fB--purge\fR[=\fIN_DAYS\fP]
purge expired files; optional argument 'N_DAYS' overrides 'expire_age'
value from the configuration file (Examples: \fB-g90\fR, \fB--purge\fR=\fI90\fP)

By default, purging is disabled ('expire_age' is set to '0' in the
configuration file). To enable, set the 'expire_age' value in your
config file to a value greater than '0'

You can use '-vvg' to see when the remaining files in the waste
directories will expire.

The argument must be attached to the option, as in the examples
above. If a space separates them, rmw reads 'N_DAYS' as the name of
a file to remove.

To purge from a scheduled job, keep 'expire_age' at '0' so that
normal runs never purge, and let a cron job give the number of days:

.EX
30 4 * * 0 rmw -g45 >> "$HOME/.local/state/rmw-purge.log" 2>&1
.EE

See the FAQ for the full example, including log rotation:

\[la]https://theimpossibleastronaut.github.io/rmw\-website/faq.html#can\-rmw\-be\-run\-as\-a\-scheduled\-job\-to\-purge\-expired\-files\[ra]

.TP
\fB-o\fR, \fB--orphaned\fR
check for orphaned files (maintenance)

An orphan is an item in a waste directory that has no corresponding
\fB\&.trashinfo\fP file, or vice versa. This option is intended primarily
for developers. Orphans may happen while testing code changes or if rmw
is unintentionally released with a bug.

A file that has no \fB\&.trashinfo\fP is repaired by \fB-o\fR alone (a new
\fB\&.trashinfo\fP is created for it). Deleting the opposite kind of orphan, a
\fB\&.trashinfo\fP with no matching file, is only done during a purge and
requires force to be given twice, as in \fBrmw -offg\fP (\fB-o -f -f -g\fR).
(see also:

\[la]https://theimpossibleastronaut.github.io/rmw\-website/faq.html#dot_trashinfo\[ra])

.TP
\fB-f\fR, \fB--force\fR
allow purging of expired files

By default, force is not required to enable the purge feature. If you
would like to require it, add 'force_required' to your config file.

.TP
\fB--empty\fR
completely empty (purge) all waste directories

.TP
\fB-r\fR, \fB-R\fR, \fB--recursive\fR
option used for compatibility with rm (recursive operation is enabled by
default)

.TP
\fB--top-level-bypass\fR
bypass protection of top-level files (added in v0.9.0)

.TP
\fB-v\fR, \fB--verbose\fR
increase output messages

.TP
\fB-w\fR, \fB--warranty\fR
display warranty

.TP
\fB-V\fR, \fB--version\fR
display version and license information

.SH RESTORING
.TP
\fB-z\fR, \fB--restore\fR \fIFILE(s)\fP
To restore items, specify the path to them in the \fIfiles\fP subdirectory of
a waste folder (wildcards ok).

When restoring an item, if a file or directory with the same name
already exists at the destination, the item being restored will have a
time/date string (formatted as "_%H%M%S-%y%m%d") appended to it
(e.g. 'foo_164353-210508').

.TP
\fB-s\fR, \fB--select\fR
select files from list to restore

Displays a list of items in your waste directories. You can use the
left/right cursor keys to switch between waste directories. Use the
space bar to select the items you wish to restore, then press enter to
restore all selected items.

The list opens on the waste directory of your current filesystem. If
no waste directory is on that filesystem, it opens on the first one in
your list instead.

When the output is not a terminal (for example, piped to another
program), rmw does not open the menu. Instead it prints the path of
that waste directory, followed by the names of the items in it.

.TP
\fB-u\fR, \fB--undo-last\fR
undo last move

Restores files that were last rmw'ed

.TP
\fB-m\fR, \fB--most-recent-list\fR
list most recently rmw'ed files


.SH CONFIGURATION
Configuration is optional. With no configured WASTE folder, rmw moves each
file to the trash on the file's own filesystem: files on the home filesystem
go to the FreeDesktop home trash (~/.local/share/Trash, the same trash your
desktop uses), and files on other filesystems go to a trash at the top of
that filesystem. These are created when first needed.

.PP
Add WASTE lines only for special cases, such as keeping rmw's files separate
from the desktop trash (uncomment the \fBWASTE = $HOME/.local/share/Waste\fP
line in the generated config), a folder on removable media, or a \fBno-add\fP
folder. Each WASTE folder must be on its own line; two WASTE folders cannot
be specified on the same line.
.TP
\fBWASTE=/mnt/flash/.Trash-$UID, removable\fP
When using the removable attribute, you must also manually create the
directory

.TP
\fBWASTE = /path, no-add\fP
The "no-add" attribute tells rmw to never move files into this folder.
rmw still lists it, restores files from it, and purges old files in it.
This is useful for a folder you want to empty over time but no longer add
to. You can combine attributes, for example "removable, no-add".

.TP
\fBexpire_age = 45\fP
rmw will permanently delete files that have been in the waste (or
trash) for more than 45 days.


.SH ENVIRONMENT
These variables are set by rmw's meson test suite to run the code in a
controlled environment. They are not meant for normal use, and setting them
yourself is strongly discouraged. See the code-testing page on the rmw
website for more details.
.TP
\fBRMW_DISCOVERY\fP
Set to "off" to stop rmw from scanning real mount points for $topdir
trash folders. Any other value (or leaving it unset) keeps discovery on.

.TP
\fBRMW_FAKE_YEAR\fP
Set to "true" to write the year 1999 as the deletion date, so the test
suite can exercise the purge feature.

.TP
\fBRMW_FAKE_HOME\fP
Deprecated; it will be removed in a future release. To choose a test home,
set \fBHOME\fP (with \fBXDG_DATA_HOME\fP and \fBXDG_CONFIG_HOME\fP) yourself; to
control mount discovery, use \fBRMW_DISCOVERY\fP instead.


.SH FILES
On some systems, $HOME/.config and $HOME/.local/share may be replaced
with $XDG_CONFIG_HOME and $XDG_DATA_HOME
.TP
\fI$HOME/.config/rmwrc\fP
configuration file

.TP
\fI$HOME/.local/share/rmw/purge-time\fP
text file that stores the time of the last purge

.TP
\fI$HOME/.local/share/rmw/mrl\fP
text file containing a list of items that were last rmw'ed


.SH NOTES
rmw does not move items from one file system to another. When you rmw a
file, it looks for a waste directory on the same file system. It checks
the waste directories in your configuration file first. If none match, it
uses the trash for that file system, as described by the FreeDesktop.org
Trash specification: the home trash (~/.local/share/Trash) for files on the
home file system, or a trash at the top of the file system (for example,
"/mnt/disk/.Trash-1000") for other file systems. If one already exists, rmw
uses it; if not, rmw creates it. (Moves between btrfs or bcachefs subvolumes
are the exception; see BTRFS AND BCACHEFS below.)

.PP
rmw does not create a trash directory on file systems that are not meant
to hold one, such as temporary (tmpfs) or network file systems. On those,
if no configured waste directory matches, rmw refuses to remove the file,
the same way desktop file managers do. A trash directory that already
exists on such a file system is still used.

.PP
Because the default home trash is the same one your desktop uses, enabling
purging (an \fBexpire_age\fP greater than 0) lets rmw permanently delete old
items that your file manager placed in the trash too, not only items removed
with rmw. Purging is off by default.

.SH DESKTOP INTEGRATION
Items are moved to the trash in the same manner as the "move to trash"
option in your desktop file manager. By default rmw uses the same trash
your desktop uses (the FreeDesktop home trash, ~/.local/share/Trash), so an
item removed with rmw appears in your desktop trash and can be restored from
either one.

.PP
To keep rmw's files separate from the desktop trash instead, uncomment this
line in your configuration file:

.EX
WASTE = $HOME/.local/share/Waste
.EE

.PP
(On macOS rmw does not integrate with the system trash; the default
~/.local/share/Trash is used.)

.PP
When rmw'ing an item, if a file or directory with the same name already
exists in the waste (or trash) directory, it will not be overwritten;
instead, the current file being rmw'ed will have a time/date string
(formatted as "_%H%M%S-%y%m%d") appended to it (e.g. 'foo_164353-210508').

.SH REMOVABLE MEDIA
The first time rmw is run, it will create a configuration file.
Waste directories will be created automatically (Except for when the
\&',removable' option is used; see below) e.g., if '$HOME/.local/share/Waste'
is uncommented in the config file, these two directories will be created:

.EX
$HOME/.local/share/Waste/files
$HOME/.local/share/Waste/info
.EE

.PP
If a WASTE directory is on removable media, you may append ',removable'.
In that case, rmw will not try to create it; it must be
initially created manually. When rmw runs, it will check to see if the
directory exists (which means the removable media containing the
directory is currently mounted). If rmw can't find the directory, it is
assumed the media containing the directory isn't mounted and that
directory will not be used for the current run of rmw.

.PP
With the media mounted, once you manually create the waste directory
for that device (e.g. "/mnt/flash/.Trash-$UID") and run rmw, it will
automatically create the two required child directories "files" and "info".

.SH BTRFS AND BCACHEFS
rmw supports moving files across subvolumes on btrfs and bcachefs
filesystems. Because the kernel reports subvolumes with different
device numbers, a cross-subvolume move would normally fail with a
cross-device error; rmw detects this case and performs a reflink
clone-then-delete instead, preserving the expected trash semantics.

.PP
To use this feature, define a WASTE directory on the destination
subvolume in your configuration file. If your waste directory is on
a different subvolume than the files you want to remove, rmw will
handle the move transparently.


.SH EXAMPLES
.SH RESTORING
.EX
rmw -z ~/.local/share/Waste/files/foo
rmw -z ~/.local/share/Waste/files/bars*
.EE


.SH AUTHORS
Project Manager: Andy Alt

.PP
The RMW team: see AUTHORS.md


.SH REPORTING BUGS
Report bugs to 
\[la]https://github.com/theimpossibleastronaut/rmw/issues\[ra]\&.


.SH COPYRIGHT
Copyright © 2012-2026 Andy Alt

.PP
License GPLv3+: GNU GPL version 3 or later 
\[la]https://gnu.org/licenses/gpl.html\[ra]\&.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.


.SH SEE ALSO
mv(1), rm(1), rmdir(1)

.PP
Full documentation at: 
\[la]https://theimpossibleastronaut.github.io/rmw\-website/\[ra]