prune-disk

prune-disk is a terminal UI for finding large or old filesystem entries and deleting them after confirmation.

It is meant for local cleanup work. By default, deletes move entries to the trash. Permanent deletion is available as an explicit mode and bypasses the trash.

Safety Warning

prune-disk deletes files. Permanent deletion bypasses the trash, and even trash-based deletion may be difficult or impossible to recover from on some systems.

Review selected paths before confirming deletion. The authors and contributors provide this software as-is, with no guarantees of correctness, safety, data recovery, or fitness for any purpose. You are responsible for backups and for the consequences of using the tool.

Install

cargo install --path .

Builds from a Git checkout report the current commit, with a -dirty suffix when the checkout has changes. Builds without Git metadata use the package version instead. Set PRUNE_DISK_BUILD_VERSION to override either:

env PRUNE_DISK_BUILD_VERSION=release-1.2.3 cargo install --path .

Usage

prune-disk --root /path/to/inspect

Common options:

prune-disk --root /path/to/inspect --trash
prune-disk --root /path/to/inspect --permanent
prune-disk --root /path/to/inspect --delete-mode trash
prune-disk --root /path/to/inspect --delete-mode permanent
prune-disk --version

Configuration and themes

Settings use TOML. On macOS and Linux, the default file is ~/.config/prune-disk.toml, or $XDG_CONFIG_HOME/prune-disk.toml when XDG_CONFIG_HOME is an absolute path. Windows uses %APPDATA%\prune-disk.toml. Use prune-disk --config /path/to/settings.toml to read a different file.

Print a complete default config, including comments describing all three choices:

prune-disk --print-default-config

The command writes only TOML to stdout and exits without opening the UI or reading an existing config. For example, the theme setting is:

theme = "plum-teal-peach"

Available themes are slate-blue-cream, plum-teal-peach (the default), and navy-gray-mint. Each has distinct cursor-only, selected-only, and combined backgrounds with explicit RGB text colors. A > marks the cursor and [x] marks selected entries, so the states also differ without color. Highlighted rows stay undimmed while their sizes refresh; the State column retains the stale indication.

To choose your own backgrounds, replace the theme = "..." assignment with this table (use one form or the other):

[theme]
cursor = "#34283D"
selected = "#48988C"
cursor_selected = "#FFF1D6"

All three fields are required and accept six-digit #RRGGBB colors, with either uppercase or lowercase hex digits. For each custom background the tool chooses black or white text, whichever has the greater contrast. Presets keep their existing text colors. Repeated backgrounds are allowed; cursor and selection marks still identify the states when the colors are the same. --print-default-config includes this custom form as a commented example.

A missing default file uses the default theme. An explicitly requested missing file, invalid TOML, unknown setting, or unknown theme produces an error before the terminal UI starts. Changes take effect the next time the tool starts.

Controls

• Up / Down: move the cursor.
• Page Up / Page Down: move one page.
• Home / End: jump to the first or last item without changing selection.
• Left: go to the parent directory or previous header.
• Right: enter a directory or next header.
• Enter or s: sort by the selected header.
• f: edit filters, starting with minimum age; Tab or Down moves to minimum size.
• Shift+f: clear filters.
• Space: toggle selection; hold while using Up, Down, Page Up, or Page Down to select or deselect every item crossed.
• Delete or d: delete the current row or selection after confirmation.
• T: empty the trash after confirmation.
• r: refresh the current directory.
• ?: show or dismiss help.
• Esc: clear selection or dismiss dialogs.
• q or Ctrl-C: quit.

Mount free space and used percentage refresh about once a second during deletion or Empty Trash, including when a single directory takes a long time to finish. The last reading stays visible while a query runs. Completion triggers a final measurement, including after a failure that may have removed some files.

The status line shows completed/total disk size and elapsed deletion time. It remains visible while a notice or dialog is open. When every selected entry has a complete, current size measurement, the figures are labelled scanned. If a starting size is unknown, estimated, or stale, the status keeps the bytes it can confirm, labels them partial, and uses + to mean "at least"; ? means no total is known yet. For example, 2 MiB+ / 10 MiB+ (partial) means at least 2 MiB completed out of at least 10 MiB. This uses allocated bytes on Unix and file lengths on other platforms. During Permanent deletion on macOS, Linux, and Android, successful file removals advance the size about once per second, including inside one unfinished directory. Total and the bytes in Filtered by date decrease when those removals affect their rows. The date footer counts recent entries hidden by the age filter. For example, removing 4 MiB from a hidden 8 MiB directory leaves 4 MiB in that footer while the directory still exists. These figures count each removed file name's allocated data blocks, including each hard-link name. They do not measure reclaimed filesystem capacity.

The scanned fraction starts from the selected entries' scanned sizes. Reported removals advance it; when a selected entry finishes, its remaining scanned estimate counts as completed without reducing live totals again. For an entry without a reliable starting size, only reported removals can advance its partial figures. Empty Trash by itself reports Size: unknown; it does not erase figures from an overlapping selected deletion. After a partial failure, successfully removed bytes stay completed and the remaining estimate is shown as failed, so the final fraction can remain below 100%. Trash and deletion on other platforms advance on whole selected entries with reliable starting sizes. If another process creates a new entry at a path whose deletion has finished, a delayed completion message from the earlier deletion cannot change the new entry's displayed size. Overlapping deletions share one elapsed period and total; the final summary remains until the next deletion starts.

Ancestor totals affected by deletion keep their known value, adjusted for successful Permanent removals, labelled stale and dimmed like rows awaiting refresh. A complete scan started after the affected deletion finishes can replace that value. Scans that overlap deletion cannot replace the retained size. Navigation preserves these byte adjustments. A newly observed replacement entry, or one whose cached size was discarded, stays unknown until it can be measured safely. Stale totals are not reused as complete cache entries.

Permanent deletion on macOS, Linux, and Android traverses opened directory handles without following replacement symlinks. Permission repair adds owner permissions only to opened directories inside the selected tree; it leaves the outside parent and regular-file modes alone. Deletion continues through an opened directory after another process renames it. Deletion skips detected replacements and reports the affected selected entry as failed. A replacement made between the final identity check and removal can still cause a replacement file or empty directory to be removed. Traversal protection begins when the backend opens the selected directories, not when the listing was scanned. It holds them open while they wait for deletion. For example, if A is renamed after it is opened and a new directory takes its name, traversal continues through the original A. Open handles grow with selected directory count and traversal depth. Reaching the open-file limit can leave some selected entries undeleted, with failures reported. Deletion keeps its existing behavior of crossing mounts, while byte accounting excludes subtrees on other devices.

The deletion backend does not report every directory affected by moving entries to Trash or emptying Trash. These operations conservatively mark directory totals stale, including unrelated folders, and refresh the current view when they finish. Later visits may rescan other folders to replace their retained totals.

License

GNU General Public License v3.0 only. See COPYING.