Skip to main content

Recovery

linux-cleanup has no undo. This page is about working out what was removed and what your real options are.

Stop writing to the disk first

If something irreplaceable was deleted and you intend to attempt file-carving recovery, stop using the filesystem now. Every write reduces the chance of recovering unlinked data.

That applies only to the genuinely irreplaceable categories. For a cache, skip it — just let the tool re-fetch.

1. Inspect the available record​

A run can leave a local log. A guided walkthrough can also leave a JSON session record unless reporting was disabled. Neither is a complete per-file deletion record or a backup.

# The most recent session log
less "$(ls -t ~/.linux-cleanup/logs/cleanup-*.log | head -1)"

# The latest walkthrough record, if one exists
jq '.' "$(ls -t ~/.linux-cleanup/reports/report-*.json | head -1)"

To search retained logs for a specific path:

grep -rn 'the-filename-you-are-missing' ~/.linux-cleanup/logs/

No match does not prove the tool left that file alone. A helper may report a whole cache directory or a command rather than each file, and --cleanup-logs can remove a run's log. Check the selected mode and target roots too.

Narrow to a single session's steps:

jq '.steps[] | select(.status == "ran")' \
"$(ls -t ~/.linux-cleanup/reports/report-*.json | head -1)"

2. Confirm it was not simply refused​

Refusals are logged too. If you find a line like this, nothing was deleted:

✗ REFUSE: protected path: /home/you/Documents/notes

See Protected paths.

3. Decide what is actually recoverable​

What was deletedRecovery
Package-manager cacheAutomatic. The next install re-downloads it
Browser cacheAutomatic. Rebuilds as you browse
Gradle cache or wrapper distroAutomatic. Next build re-fetches — expect a slow first build
Cypress / Playwright binariesRe-run the install step for that tool
node_modulesyarn install or npm install in the project
Android AVDRecreate in Android Studio. The profile config is gone; the system image re-downloads
Editor extension versionReload the editor window; reinstall if genuinely missing
apt cache, journal, snap revisionsRegenerate on their own. Nothing to do
Personal file from ~/DownloadsOnly from your own backup, or re-download from the source
Partial downloadNot recoverable. Restart the download

Regenerating the common ones​

# In the affected project
yarn install # or: npm install / pnpm install

# Test-runner binaries
npx cypress install
npx playwright install

# Flutter
flutter pub get

Nothing here needs the tool's involvement — you are just letting each tool do what it does on a cold cache.

4. If it was genuinely irreplaceable​

Realistically, in order:

  1. Your own backup. Timeshift, Borg, restic, rsync snapshot, cloud sync — whatever you run. This is the only reliable answer.
  2. The original source. A downloaded file can be downloaded again. Check your browser history for the URL.
  3. A sync service's trash. Dropbox, Nextcloud, Google Drive and similar keep deleted files server-side for a retention window. If the directory was synced, look there.
  4. File-carving tools — extundelete, testdisk, photorec. These work on unlinked inodes and are a long shot on a busy filesystem, especially SSDs with TRIM enabled. Unmount the filesystem first, or work from a live USB, and never write recovered data back to the same device.
Be honest with yourself about step 4

On a mounted, actively-used SSD with TRIM, carving usually recovers nothing. It is worth attempting only for something genuinely important, and only after you have stopped writing to the disk.

5. Stop it happening again​

ChangeEffect
Run --scan before every cleanupYou see the outcome while it is still hypothetical
Move valuables out of ~/Downloads~/Documents and ~/Desktop are protected
Skip step 7 in the walkthroughPersonal files then need a deliberate separate run
Raise the threshold: -d 365Only genuinely ancient files become candidates
Never use -y outside --all-safe on a trusted machine-y cannot touch personal data, but you see decisions only afterwards
Set up a real backupThe only thing that makes any deletion recoverable

6. If the tool did something it should not have​

If a deletion happened inside a protected path, or a current editor extension version was removed, or anything else contradicts the documented guards — that is a bug worth reporting.

linux-cleanup --debug-bundle
linux-cleanup --feedback

Include the log and a walkthrough record if one exists. See Send a bug report.

Next​