From 6eed53646b7727b19d92025c5c2a00364ba2ae08 Mon Sep 17 00:00:00 2001
From: "David T. Sadler" <davidtsadler@googlemail.com>
Date: Sat, 22 Aug 2026 21:21:42 +0100
Subject: Update README.md with instructions on how to manage submodules

---
 README.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/README.md b/README.md
index 810e81a..c164910 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,33 @@ My custom configuration files.
 2. Run the installation script:
    `./install.sh`
 
+## Submodule Management
+
+### Sync Existing Submodules
+
+After running `git pull` on an existing setup or setting up a new machine, restore submodules to their exact pinned commits:
+
+```bash
+git submodule update --init --recursive
+```
+
+### Update Submodules to Latest Upstream Releases
+
+To bump top-level submodules (like plugins) to their newest remote commits without breaking internal nested dependencies:
+
+```bash
+# Fetch latest commits for top-level submodules
+git submodule update --remote
+
+# Reset nested submodules to what top-level submodules expect
+git submodule update --init --recursive
+
+# Commit updated submodule pointers
+git add .
+git commit -m "Update submodules to latest versions"
+git push
+```
+
 ## Neovim Keymaps
 
 <!-- BEGIN-NEOVIM-KEYMAPS -->
-- 
cgit v1.2.3-13-gbd6f