write a README

1 files changed, 54 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3d65e4d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,54 @@
+The main functionality
+======================
+
+`pristine-etc-keeper` is a program that hooks into `etckeeper` to
+maintain a git branch that is a "pristine" version of `/etc`--just the
+raw files provided by installed packages.
+
+It assumes that the real directory being tracked by etckeeper is
+`/etc`, that the VCS using used is `git`, and that the system package
+manager is `pacman`.
+
+It works by asking `pacman` which packages are installed, and
+extracting `/etc` files from the cached copies of the package
+tarballs.  A litteral pristine version of `/etc` lives at
+`/var/lib/pristine-etc/etc`.
+
+The spool (AKA, invoking pristine-etc-keeper)
+=============================================
+
+It would be really simple to just provide a program that you run when
+you want to update the pristine-etc.  Unfortunately,
+pristine-etc-keeper is very slow, and this would make many tasks
+painful.  So we run it asyncronously.
+
+But that opens a whole other slew of problems.  What happens if we try
+to run it again while it is already running?  The second instance
+should wait until the first instance is finished.  But only one
+instance should be queued at a time; if a 3rd instance tries to start,
+it should just be discarded/merged with the one already waiting.
+
+A simple thing to do would have been to write a daemon that is always
+running, waiting to receive a signal that it should run.  I don't like
+that because I don't really want the process to be long lived.
+
+So, I created a sort of spool.  You can think of the spool as a queue
+of jobs to run, and that when you run `pristine-etc-keeper.service`,
+it runs repeatedly until the spool is empty.  What makes this
+different than the job queue that I just described it as is that it
+drains the entire spool each run; if it has to run again, it's because
+the spool filled back up while it was running.
+
+Anyway, to put a job in the spool, you do 4 things:
+
+  1. `open(2)` the file `/var/lib/pristine-etc/lock`
+  1. `flock(2)` the lockfile file descriptor with an exclusive lock
+  2. write to /var/lib/pristine-etc/spool with your message and
+     `O_CREAT` | `O_APPEND`.
+  3. close the `flock`ed file descriptor
+  4. run `systemctl start pristin-etc-keeper.service` to start (if
+     nescessary) it draining the spool.
+
+You may wish to run
+`systemctl reset-failed pristin-etc-keeper.service` before trying to
+start it.