From 9f746adc707a2abfac6bc8dda779b2f45e317a3c Mon Sep 17 00:00:00 2001
From: "Collin J. Doering" <collin@rekahsoft.ca>
Date: Mon, 31 Oct 2022 23:49:52 -0400
Subject: [PATCH] README.org: Various updates to README; restructuring & new
 sections

---
 README.org | 89 +++++++++++++++++++++++++++++++++---------------------
 1 file changed, 54 insertions(+), 35 deletions(-)

diff --git a/README.org b/README.org
index 582d7f5..230570e 100644
--- a/README.org
+++ b/README.org
@@ -20,10 +20,7 @@ These are the dotfiles of the author, managed using guix-home, in combination wi
 - ~README.org~           :: Org-mode[fn:4] documentation
 - ~TODO.org~             :: Org-mode todo's, known issues and future aspirations
 - ~home-manifest.scm~    :: Guix manifest used for cuirass builds (and as needed via the cli)
-- ~user-config~          :: Configuration for various programs managed using gnu stow, not
-  guix-home (just yet)
-- ~user-config-unused~   :: Configuration for various programs (managed using gnu stow) that
-  is no longer used
+- ~user-config~          :: Configuration for various programs managed using a combination of gnu stow and guix-home
 
 ** Guix Channel File
 
@@ -59,23 +56,7 @@ following.
   guix home reconfigure -e '(@ (rekahsoft guix-config home) %home)'
 #+end_src
 
-** TODO Working with Local Sources
-
-Clone this repository.
-
-#+begin_src shell
-  git clone <repo> ~/.dotfiles
-  cd ~/.dotfiles
-#+end_src
-
-To deploy changes that have not yet been commit, the ~-L|--load-path~ option to guix can be
-used like so.
-
-#+begin_src shell
-  guix home reconfigure -L .guix -e '(@ (rekahsoft guix-config home) %home)'
-#+end_src
-
-** TODO Legacy Configuration
+* TODO Legacy Configuration
 
 Configurations for a variety of programs are available to be 'installed' by symbolically
 linking them into ~$HOME~ using stow. This process is simplified by the provided ~Makefile~,
@@ -91,7 +72,7 @@ is still managed using the 'legacy' stow method described here.
   make
 #+end_src
 
-* TODO Makefile Usage
+** TODO Makefile Usage
 
 ~Makefile~ is expected to be become unnecessary after this configuration is managed by Guix home instead of using stow.
 
@@ -107,7 +88,7 @@ Notes:
   If no [packages] are listed, all packages are actioned upon via the all target
 #+end_verse
 
-** Examples
+*** Examples
 
 #+begin_src shell
   # Install a subset of the entire configuration
@@ -126,6 +107,56 @@ Notes:
   make DELETE=true bash
 #+end_src
 
+* Working with Local Sources
+
+Clone this repository.
+
+#+begin_src shell
+  git clone <repo> ~/.dotfiles
+  cd ~/.dotfiles
+#+end_src
+
+This home configuration is presented as a guix channel, and because of this, changes normally
+need to be committed in order to be tested. However, the ~-L|--load-path~ option to guix can
+be used to explicitly reference this repositories' uncommitted channel sources in ~.guix~
+(using ~-L .guix~).
+
+Additionally, to test with a different set of channels (for example, to check if this home
+configuration works following updates to the guix, nonguix or some other dependent channel),
+~guix time-machine~ can be used, explicitly referencing a channel file with ~-C|--channel~.
+When ones local guix channels match ~channels.scm~, ~guix time-machine ...~ does not need to
+be used because it has no effect and just adds overhead.
+
+** Deploy
+
+#+begin_src shell
+  guix time-machine -C channels.scm -- home reconfigure -L .guix -e '(@ (rekahsoft guix-config home) %home)'
+#+end_src
+
+** Build
+
+#+begin_src shell
+  guix time-machine -C channels.scm -- home build -L .guix -e '(@ (rekahsoft guix-config home) %home)'
+#+end_src
+
+** Test in a container
+
+#+begin_src shell
+  guix time-machine -C channels.scm -- home container -L .guix -e '(@ (rekahsoft guix-config home) %home)'
+#+end_src
+
+** View Guix Extension Graph
+
+#+begin_src shell
+  guix home extension-graph -e '(@ (rekahsoft guix-config home) %home)' | guix shell gnome-icon-theme xdot -- xdot -
+#+end_src
+
+** View Shepherd Graph
+
+#+begin_src shell
+  guix home shepherd-graph -e '(@ (rekahsoft guix-config home) %home)' | guix shell gnome-icon-theme xdot -- xdot -
+#+end_src
+
 * Development
 
 This section details some useful tips regarding development.
@@ -142,18 +173,6 @@ Here are some useful commands for working with package upgrades on guix.
   guix time-machine -- environment -m ~/.dotfiles/home-manifest.scm -- exit
 #+end_src
 
-*** View Guix Extension Graph
-
-#+begin_src shell
-  guix home extension-graph -e '(@ (rekahsoft guix-config home) %home)' | guix shell gnome-icon-theme xdot -- xdot -
-#+end_src
-
-*** View Shepherd Graph
-
-#+begin_src shell
-  guix home shepherd-graph -e '(@ (rekahsoft guix-config home) %home)' | guix shell gnome-icon-theme xdot -- xdot -
-#+end_src
-
 *** Updates that modify zsh site-functions (completions)
 
 These updates require additional manual effort, otherwise completions don't show up.