From 3dadccdbc6f5d30833b2ca53c6170a8847745e70 Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Sat, 15 Jul 2017 18:53:20 +0100
Subject: [PATCH] keys.delete-keeper: Add commentary, because it's bit
 complicated.

---
 keys.delete-keeper | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/keys.delete-keeper b/keys.delete-keeper
index 1e3f3ec..778f696 100755
--- a/keys.delete-keeper
+++ b/keys.delete-keeper
@@ -32,25 +32,37 @@ KEEPER
 Delete the keeper set named KEEPER.
 HELP
 
+## Parse the command line.
 case $# in 1) ;; *) usage_err ;; esac
 keeper=$1
 checkword "keeper set label" "$keeper"
 
+## Check that the set actually exists.
 cd $KEYS/keeper
 if [ ! -d $keeper ]; then
   echo >&2 "$quis: unknown keeper set \`$keeper'"
   exit 1
 fi
 
+## Make sure that there aren't recovery keys which would be orphaned by
+## deleting this keeper set.
 unset deps
 if [ -d $KEYS/recov ]; then
   cd $KEYS/recov
+
+  ## Work through the available recovery keys.
   for r in $(find . -type l -name current -print); do
     r=${r#./}; r=${r%/current}
     if ! expr >/dev/null "Q$r" : "Q$R_LABEL"; then continue; fi
+
+    ## Now work through the instances.
     for ri in $r/*; do
       i=${ri##*/}
       case "$i" in *[!0-9]*) continue ;; esac
+
+      ## For each recovery key, make sure that: either it doesn't depend on
+      ## this keeper set, or it also depends on at least one other set.  If
+      ## not, add it to the `deps' list.
       this=nil others=nil
       for kp in $r/current/*.param; do
 	k=${kp##*/}; k=${k%.param}
@@ -60,6 +72,8 @@ if [ -d $KEYS/recov ]; then
     done
   done
 fi
+
+## If we found any hard dependencies, report a failure.
 case "${deps+t}" in
   t)
     echo >&2 "$quis: deleting keeper \`$keeper' would orphan recovery keys:"
@@ -68,16 +82,24 @@ case "${deps+t}" in
     ;;
 esac
 
+## Disentangle the dependent recovery keys from this keeper set.
 if [ -d $KEYS/recov ]; then
   cd $KEYS/recov
+
+  ## Work through the recovery keys again.
   for r in $(find . -type l -name current -print); do
     r=${r#./}; r=${r%/current}
     if ! expr >/dev/null "Q$r" : "Q$R_LABEL"; then continue; fi
+
+    ## Remove the keeper data from the key's instances.
     for ri in $i/*; do
       i=${ri##*/}
       case "$i" in *[!0-9]*) continue ;; esac
       rm -f $ri/$keeper.*
     done
+
+    ## Work through the current keepers, and remove our keeper's name from
+    ## the list.
     changep=nil
     while read k rest; do
       case $k in $keeper) changep=t ;; *) echo "$k $rest" ;; esac
@@ -89,6 +111,7 @@ if [ -d $KEYS/recov ]; then
   done
 fi
 
+## Finally, actually delete the keeper keys.
 cd $KEYS/keeper
 rm -r $keeper
 
-- 
2.11.0