From 69df4744c7ba4dc0f4553faf1ff24387f524c0a9 Mon Sep 17 00:00:00 2001
From: Adrian Wannenmacher <tfld@tfld.dev>
Date: Sat, 13 Feb 2021 19:10:36 +0100
Subject: [PATCH] Update readme

---
 README.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)

diff --git a/README.md b/README.md
index 14c4a12..2653f6d 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,105 @@
 # snap-pac-uki
+
+## What is this?
+
+This is a collection of scripts, pacman hooks and and systemd units for creating
+and managing unified kernel images (UKIs) based on snapper. It originally
+expected to be executed as a pacman hook after `snap-pac`, but this is no longer
+required (though the name remains).
+
+## Installation
+
+### Prerequisites
+
+This tool expects that you already set up snapper. It also expects that each
+snapshots linux and initramfs files (`/boot/vmlinuz-linux` and
+`/boot/initramfs-linux.img`) as well as a kernel command line file
+(`/etc/snap-pac-uki/kernel-cmd`) are available within each snapshot.
+
+The fallback initramfs (`/boot/initramfs-linux-fallback.img`) and fallback
+command line file (`/etc/snap-pac-uki/kernel-cmd-fallback`) are only required
+on the current system.
+
+EFI boot options are only created for each snapshot. If you want the UKIs
+created for the current system, you'll need to add boot entries yourself:
+
+```bash
+# template
+efibootmgr -c \
+    -d <EFI DEVICE> \
+    -p <EFI PARTITION NUMBER> \
+    -l <EFI PATH> \
+    -L <LABEL>
+
+# example
+efibootmgr -c \
+    -d /dev/nvme0n1 \
+    -p 1 \
+    -l "\EFI\Linux\arch-linux.efi" \
+    -L "Arch Linux"
+
+# example for fallback
+efibootmgr -c \
+    -d /dev/nvme0n1 \
+    -p 1 \
+    -l "\EFI\Linux\arch-linux-fallback.efi" \
+    -L "Arch Linux (Fallback)"
+```
+
+### Using the install script
+
+1. You can install the dependencies of this program with the following command:
+
+   ```bash
+   pacman -S fish efibootmgr jq ripgrep sbsigntools sed snapper
+   ```
+
+2. Download the latest release from [here][releases] and unpack it.
+
+3. Then run the install script (you need to be in the same directory):
+
+   ```bash
+   ./install.fish
+   ```
+
+## Usage
+
+### Creating snapshot UKIs
+
+This creates a new UKI for all snapshots where none is found:
+
+```bash
+snap-pac-uki snapshots
+```
+
+### Create current UKIs
+
+This creates a new UKI for the current system (including a fallback variant):
+
+```bash
+snap-pac-uki current
+```
+
+### Clean up UKIs
+
+This removes all UKIs without corresponding snapshot (solely based on number):
+
+```bash
+snap-pac-uki clean
+```
+
+### Enable periodic cleanups using systemd timer
+
+```
+systemctl enable --now snap-pac-uki-cleanup.timer
+```
+
+## Uninstall
+
+Simply run the following command in this directory:
+
+```bash
+./uninstall.fish
+```
+
+[releases]: https://git.tfld.dev/tfld/snap-pac-uki/releases