Skip to main content

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.txt with 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​

A bundle contains paths from your machine

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:

IncludeExample
Distro and versionlsb_release -d
Bash versionbash --version | head -1
Tool versionlinux-cleanup --version
The exact commandlinux-cleanup --all-safe -y -d 30
Expected versus actual"expected the Gradle wrapper kept, it was deleted"
The bundleAttach 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​

RouteUse for
GitHub issuesBugs, feature requests — preferred, public
aoneahsan@gmail.comAnything you would rather not post publicly
A pull requestYou 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​

Release check and local reports

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​