From 7f0616d6b1fa66de82b24aef0b9691ab06e8a7a0 Mon Sep 17 00:00:00 2001
From: bisco <bisco@younerd.org>
Date: Wed, 3 Jun 2026 18:58:49 +0200
Subject: [PATCH] added License specification into script; added a wide
 description into README.md

---
 README.md | 188 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 plonk.sh  |   1 +
 2 files changed, 184 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 12165d8..a4d6677 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,186 @@
-# plonk
+# PLONK
 
-PLONK - PLONK Leaves Only Needed Kernels
+**PLONK** stands for:
 
-This script removes old Debian kernel packages.
-It also purges old kernel packages left in "rc" state.
+> **PLONK Leaves Only Needed Kernels**
 
-In short: old kernels go plonk.
\ No newline at end of file
+It is a small Debian-oriented shell script used to list, simulate and purge old Linux kernel packages.
+
+In short:
+
+> old kernels go plonk.
+
+## What it does
+
+PLONK helps keeping Debian systems clean by removing old kernel packages while preserving the kernels that are still needed.
+
+It can:
+
+* list old installed kernel packages;
+* list kernel packages left in `rc` state;
+* simulate the purge operation before doing anything;
+* purge old kernel packages;
+* keep a configurable number of installed kernels;
+* always keep the currently running kernel;
+* avoid removing Debian kernel meta-packages such as `linux-image-amd64`.
+
+## Why
+
+Debian systems can accumulate old kernel packages over time, especially on long-lived servers or frequently updated machines.
+
+Sometimes old kernels are already removed but still appear in `dpkg` output with `rc` status, meaning that only residual configuration files are left.
+
+PLONK tries to clean both cases in a conservative way.
+
+## Requirements
+
+PLONK requires:
+
+* Debian;
+* `bash`;
+* `apt-get`;
+* `dpkg-query`;
+* root privileges when actually removing packages.
+
+It is mainly written and tested with Debian in mind.
+
+## Usage
+
+```bash
+plonk [option]
+```
+
+Available options:
+
+```text
+-l | --list      : list old kernel packages
+-n | --dry-run   : simulate old kernel packages removal
+-r | --remove    : remove old kernel packages
+-k | --keep NUM  : number of kernels to keep
+-y | --yes       : assume yes when removing packages
+-h | --help      : show help and exit
+```
+
+## Examples
+
+List old kernel packages and residual `rc` packages:
+
+```bash
+./plonk --list
+```
+
+Simulate the purge operation:
+
+```bash
+./plonk --dry-run
+```
+
+Remove old kernel packages:
+
+```bash
+sudo ./plonk --remove
+```
+
+Remove old kernel packages and keep three installed kernels:
+
+```bash
+sudo ./plonk --remove --keep 3
+```
+
+Remove old kernel packages without confirmation:
+
+```bash
+sudo ./plonk --remove --yes
+```
+
+## Recommended workflow
+
+Before removing anything, always run:
+
+```bash
+./plonk --list
+```
+
+Then run:
+
+```bash
+./plonk --dry-run
+```
+
+Only after reviewing the output, run:
+
+```bash
+sudo ./plonk --remove
+```
+
+On production servers, remote systems or machines where rollback matters, keeping more than the default number of kernels is recommended:
+
+```bash
+sudo ./plonk --remove --keep 3
+```
+
+## About `rc` packages
+
+In `dpkg` output, packages in `rc` state are already removed, but their configuration files are still present.
+
+Example:
+
+```text
+rc  linux-image-6.1.0-38-amd64  6.1.147-1  amd64  Linux 6.1 for 64-bit PCs
+```
+
+PLONK can purge those residual packages too.
+
+## Safety notes
+
+PLONK is intentionally conservative.
+
+It always keeps:
+
+* the currently running kernel;
+* at least one additional installed kernel by default;
+* the related Debian kernel ABI packages;
+* Debian kernel meta-packages.
+
+Still, kernel removal can be risky. Always check the dry-run output before purging packages.
+
+## Install
+
+Clone the repository:
+
+```bash
+git clone <repo-url>
+cd plonk
+```
+
+Make the script executable:
+
+```bash
+chmod +x plonk
+```
+
+Optionally install it system-wide:
+
+```bash
+sudo install -m 0755 plonk /usr/local/sbin/plonk
+```
+
+Then run:
+
+```bash
+plonk --help
+```
+
+## Name
+
+`plonk` is both:
+
+```text
+PLONK Leaves Only Needed Kernels
+```
+
+and the sound old kernels make when they finally disappear down the drain.
+
+## License
+
+* GPL-3.0-or-later.
\ No newline at end of file
diff --git a/plonk.sh b/plonk.sh
index 7d5b542..50aef01 100644
--- a/plonk.sh
+++ b/plonk.sh
@@ -1,4 +1,5 @@
 #!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-or-later
 # PLONK - PLONK Leaves Only Needed Kernels
 #
 # This script removes old Debian kernels