From 9e76d7838c4364c0b9c9c78f0b54629bad6e9025 Mon Sep 17 00:00:00 2001
From: Daniel Flanagan <daniel@lyte.dev>
Date: Wed, 3 Nov 2021 13:24:05 -0500
Subject: [PATCH] Add structure section to readme

---
 readme.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/readme.md b/readme.md
index d1b9580..3236a91 100644
--- a/readme.md
+++ b/readme.md
@@ -8,6 +8,44 @@ take what you like.
 ![Battlestation][battlestation-photo]
 ![Desktop Screenshot][desktop-screenshot]
 
+# Repo Structure
+
+My dotfiles are composed together by layering "environments" since I want my dotfiles to be flexible across servers, laptops, desktops, and even my phone (via Termux).
+
+    lytedev-dotfiles
+    |- common --- common to all hosts and operating systems
+    | |- bin ------- programs or scripts useful to all hosts/OSs
+    | |- data ------ shared storage for certain scripts
+    | `- {app...} -- configuration related to {app}
+    |- host ----- specific to specific hosts or types of hosts
+    | |- desktop --- for desktop-class machines
+    | |- headless -- for server-class machines with no display/GUI
+    | `- laptop ---- for portable, battery-having machines
+    `- os ------- specific to operating systems
+      |- linux -----
+      |  |- desktop ------ for desktop-class machines
+      |  |- headless ----- for server-class machines with no display/GUI
+      |  |- bin ---------- programs/scripts useful to linux machines
+      |  |- {distro...} -- configuration related to {distro}
+      |  `- {app...} ----- linux-specific configuration related to {app}
+      `- macos ----- for those stupid macbooks work tries to make you use
+
+Any environment should be able to extend the configuration of any application
+in some unique way. This isn't possible with all applications, of course, since
+some programs do not make it easy (or possible) to include multiple
+configuration files or to extend a single file by having it include others via
+globs or some other mechanism.
+
+One example of doing this well is with fish:
+
+    for s in $ENV_PATH/*/config.d.fish; source $s (dirname $s); end
+
+This way, if any environment (a dir in $ENV_PATH) has a `config.f.fish` script
+inside, it will be sourced by the main configuration file.
+
+Likewise, some setup only happens in certain environments via the
+`dotfiles-setup.d.fish` script.
+
 # Basic Setup
 
     curl -Ss https://lyte.dev/df.sh | sh