From 7170bb2048ee9b1e227baf043240b1d7b0256c4c Mon Sep 17 00:00:00 2001
From: emmett1 <me@emmett1.my>
Date: Fri, 29 May 2026 17:18:38 +0800
Subject: README.md updated

---
 README.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 72 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 8ed4ca3..f8d5939 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,73 @@
 # spm
-Simple Package Manager
+
+Simple Package Manager — a POSIX-compatible package manager for Linux.
+
+`spm` builds, installs, upgrades, and removes `.spm` packages. A package is a compressed tar archive with a filename that encodes its identity: `<name>#<version>-<release>.spm`.
+
+## Install
+
+```sh
+make install                          # install to /usr/bin/spm
+make install DESTDIR=/tmp/staging     # install to a staging directory
+make install PREFIX=/usr/local        # install to /usr/local/bin/spm
+make uninstall                        # remove spm and its man page
+```
+
+## Usage
+
+```
+spm -a              list all installed packages
+spm -b <path>       build a package from the current directory
+spm -h              print help
+spm -i <file>       install a package (requires root)
+spm -l <name>       list files installed by a package
+spm -o <file>       find which package owns a file
+spm -r <name>       remove an installed package (requires root)
+spm -u <file>       upgrade or reinstall a package (requires root)
+```
+
+## Package format
+
+`.spm` packages are compressed tar archives whose contents mirror the target filesystem tree. Files under `etc/` are automatically given a `.new` suffix during build so they don't overwrite existing configs on install — the `.new` file is moved into place only if the destination is absent or identical.
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `SPM_ROOT` | Alternate installation root (default: `/`) |
+| `SPM_FORCEINSTALL` | Skip conflict detection |
+| `SPM_VERBOSE` | Print each file as it's installed or removed |
+| `SPM_COMPRESSION` | Compression for builds: `gzip` (default), `bzip2`, or `xz` |
+
+## Database
+
+Package metadata lives under `/var/lib/spm/` (or `$SPM_ROOT/var/lib/spm/`):
+
+| Path | Contents |
+|---|---|
+| `db/<name>` | One file per package: version line + list of installed paths |
+| `perms/<name>` | Non-standard directory permissions for the package |
+| `owner/<name>` | Non-root directory ownership for the package |
+
+## Examples
+
+```sh
+# Build
+cd staged-files && spm -b /tmp/mypkg#1.0-1.spm
+
+# Install / upgrade / remove
+spm -i /tmp/mypkg#1.0-1.spm
+spm -u /tmp/mypkg#1.1-1.spm
+spm -r mypkg
+
+# Query
+spm -a              # what's installed?
+spm -l mypkg        # what files did mypkg install?
+spm -o /usr/bin/x   # what package owns /usr/bin/x?
+
+# Alternate root (chroot / container)
+SPM_ROOT=/mnt/rootfs spm -i /tmp/mypkg#1.0-1.spm
+
+# Different compression
+SPM_COMPRESSION=xz spm -b /tmp/mypkg#1.0-1.spm
+```
-- 
cgit v1.2.3