From 8a24584262a90956e012cee7b03c8c2b9f4b794c Mon Sep 17 00:00:00 2001
From: Jeff Carr <jcarr@wit.com>
Date: Mon, 20 Oct 2025 05:50:38 -0500
Subject: reworking this to make it more sane. hopefully.

---
 README.md | 63 ++++++++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 44 insertions(+), 19 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 67dbb17..8529fb0 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,51 @@
-// Copyright 2025 WIT.COM Inc Licensed GPL 3.0
+* Theory of config
 
-common config file handling for protobuf defined config files
-intended to be super simple so the code you need to write is simple.
+    * Make the defaults the same everywhere
 
-Enables Load functions:
+    * There are two types of config files:
 
-// loads ~/.config/myapp/trees.text
-cfg := new(MyPB)
-err := config.ConfigLoad(cfg, "myapp", "trees")
+        1) A super simple ENV key:value file (config.proto defined in this package)
+        2) A application defined <appname>.proto (.proto wherever you want to put it)
 
-Enables Save functions:
 
-err := cfg.Save() // it automatically knows where to save
+* 1) Basic application config.proto information
 
-### Errors ####
+    the application config.proto is loaded from, in order:
 
-if errors.Is(err, config.VersionMismatch) {
-    // protobuf structure changed
-}
-if errors.Is(err, config.ErrEmpty) {
-    // config file was empty
-}
-if errors.Is(err, config.ErrNotExist) {
-    // config file didn't exist (yes, this is the os.ExistErr)
-}
+    /usr/share/doc/appname/config.text
+    /etc/default/appname
+    ~/.config/appname/config.text
+
+    These files ONLY HAVE ENV LIKE KEY/VALUE Pairs
+
+* 2) application specific protobuf files
+
+    Application config files are always located in the same place
+    with the same name by default.
+
+    For the application "forge" using forge.proto
+
+    ~/.config/forge/forge.text
+
+    To override these defaults, set the values in the 1) protobuf
+
+* notes from the code
+
+```
+// Because you followed autogenpb's advice (you did follow it right?) you now
+// win the automation lottery.
+//
+// for this .proto file, GetProtobufName(pb) returns "repos"
+// Then, ConfigLoad(), ConfigSave(), CacheLoad() and CacheSave()
+// all do exactly what is expected:
+//
+// Automatically work with the files:
+//  ~/.config/<appname>/repos.pb
+// or
+//  ~/.cache/<appname/repos.pb
+//
+// message Repos {
+//         string                      uuid                     = 1;
+//         string                      version                  = 2;
+//         repeated Repo               repos                    = 3;
+```
-- 
cgit v1.2.3