Skip to main content

Exit codes

linux-cleanup follows the Unix convention: 0 is success, anything else is a problem. Some non-zero codes are expected and deliberately not treated as crashes.

Codes​

CodeMeaningCrash bundle
0Clean run. Every requested action completed or was declinedNo
1Generic failure — an invariant was violated. RareYes
2Argument parse error. Help is printedNo
3Update required by the public release recordNo
127Command not found — a required dependency is missingYes
130Aborted with Ctrl-C (SIGINT)No
137Killed by SIGKILL — usually the OOM killer or kill -9Yes
139Segfault. Should not happen in pure bashYes
143Terminated by SIGTERMNo
any other non-zeroUnexpected internal failureYes

An unknown flag exits 2 before cleanup. --dry-run is supported; it walks the selected mode without deleting files. See Preview before deleting.

How the crash trap decides​

The EXIT trap added in 1.3.0 evaluates in this order:

  1. Exit code is 0, or the script set its internal completion sentinel → no bundle
  2. Exit code is 130 (Ctrl-C) or 143 (SIGTERM) → no bundle. A user-initiated stop is not a crash
  3. Exit code is 2 (argument parse) → no bundle. The script printed help and stopped on purpose
  4. Anything else → write crash-<timestamp>.tar.gz to ~/.linux-cleanup/feedback/

The bundle contains the active session log, the most recent JSON record, and a short system manifest. It stays on your machine — nothing is transmitted. The tool prints the path so you can review it and decide whether to email it.

See Send a bug report.

Branching on the code​

if linux-cleanup --scan; then
echo "scan succeeded"
else
case $? in
2) echo "bad flag" ;;
127) echo "missing dependency — run --self-test" ;;
130) echo "user aborted" ;;
*) echo "unexpected failure — check ~/.linux-cleanup/feedback/" ;;
esac
fi

In cron​

linux-cleanup --all-safe -y --no-report --cleanup-logs >>~/.linux-cleanup/logs/cron.log 2>&1 || \
echo "linux-cleanup exited $?" | mail -s "cleanup failed on $(hostname)" you@example.com

Exit code 127 from a cron job almost always means the crontab used a bare command name and cron's minimal PATH could not find it. Use an absolute path — see Troubleshooting.

Diagnosing an unexpected code from a crash bundle​

The bundle's manifest records the exit code. The common ones:

CodeUsual cause
137Out-of-memory killer. Typically a find over an enormous tree
141SIGPIPE — a pipe closed early, often a tee or pager exiting
139Segfault — should never occur here; report it
127Missing dependency. Run --self-test to identify it

Next​