Send a bug report
Two commands produce everything a maintainer needs. Nothing is transmitted automatically — you review the bundle and send it yourself.
linux-cleanup --debug-bundle # package the latest log + session record
linux-cleanup --feedback # instructions, and an optional mailto draft
The quick path
linux-cleanup --debug-bundle
Writes ~/.linux-cleanup/feedback/debug-bundle-<timestamp>.tar.gz containing:
- The latest session log
- The latest JSON session record, if one exists
- A
MANIFEST.txtwith distro, kernel, bash version and self-test output
Then:
linux-cleanup --feedback
Prints what to include and offers to open a pre-filled mailto: draft with system information already
completed.
Review the bundle before sending it
Not file contents — but the log names every path touched, which means directory names, project names, and
sometimes filenames from ~/Downloads.
Inspect it first:
tar -tzf ~/.linux-cleanup/feedback/debug-bundle-*.tar.gz # list contents
tar -xzOf ~/.linux-cleanup/feedback/debug-bundle-*.tar.gz # read it in full
If something in there is sensitive, extract the bundle, remove or redact the file, and re-archive — or just send the manifest plus the specific lines that matter.
Crash bundles
Since 1.3.0, an unexpected non-zero exit writes
crash-<timestamp>.tar.gz to the same directory automatically, and prints the path.
It holds the active log, the most recent record, and a system manifest including the exit code.
The bundle is not uploaded. The release check reads a public text file, but it does not send a bundle or local paths. The bundle stays on your disk until you decide whether to share it.
Crash bundles are not written for expected exits: 0, 130 (Ctrl-C), 143 (SIGTERM) and 2
(argument error) are all excluded. See
Exit codes.
What to include
A good report is short and specific:
| Include | Example |
|---|---|
| Distro and version | lsb_release -d |
| Bash version | bash --version | head -1 |
| Tool version | linux-cleanup --version |
| The exact command | linux-cleanup --all-safe -y -d 30 |
| Expected versus actual | "expected the Gradle wrapper kept, it was deleted" |
| The bundle | Attach the tar.gz |
The most valuable line is expected versus actual. A log alone shows what happened but not why you think it was wrong.
Where to send it
| Route | Use for |
|---|---|
| GitHub issues | Bugs, feature requests — preferred, public |
| aoneahsan@gmail.com | Anything you would rather not post publicly |
| A pull request | You have a fix. MIT licensed, forks welcome |
Feature requests by description are as welcome as code. Say what you would want cleaned and why the existing modes do not cover it.
Bugs worth reporting immediately
Anything contradicting the documented safety model:
- A deletion inside a protected path
- A current editor extension version removed, not just a superseded one
- A file deleted despite being newer than
--days, without--purge-all - A personal-data mode acting without confirmation
- A network request that sends local cleanup paths or reports
Each of those is a safety-model violation rather than an inconvenience.
Privacy: what leaves your machine
At start, linux-cleanup reads one public release record over HTTPS when online. It does not upload scans, logs or crash bundles. Installing or updating a copy uses npm or GitHub.
Verify on a clone:
grep -rE 'curl|wget|http://|https://' cleanup.sh lib/ modules/ bin/
Read modules/update_check.sh for the release request and the command offered for a newer copy.
Logs, records and bundles are local files. The maintainer cannot see them, and cannot push a fix to your
machine — a new version reaches you when you re-run npx or upgrade.
Next
- Troubleshooting — check here first
- Recovery — if data was lost
- Exit codes