Fetching Content Updates is Multi-Step, Multi-Module
New content reaches lossless.group only after it moves through three repo levels and three branches. Skip a step and the site serves stale content.
- Path
- reminders/Fetching-Content-Updates-is-Multi-Step-Multi-Module.md
- Authors
- Michael Staton
- Augmented with
- Claude Code on Claude Opus 5.5
- Tags
- Submodules · Content-Pipeline · Deployment · Vercel
Fetching Content Updates is Multi-Step, Multi-Module
Content is authored in one place and rendered from another, and each hop is a separate git repo:
lossless-monorepo/content/ lossless-content repo (authoring copy)
├── content-areas/ submodule → content-areas repo
├── client-content/ submodule → lossless-client-content repo (PRIVATE)
└── projects/Water-Template-CE/ submodule → water-foundation-ce repo
lossless-monorepo/site/ lossless-site repo
└── src/generated-content/ submodule → lossless-content repo (the SAME repo as content/)
├── content-areas/ nested submodule → content-areas repo
├── client-content/ nested submodule (private; never initialized in the site copy)
└── projects/Water-Template-CE/ nested submodule (not initialized in the site copy)
A commit only reaches the website once every level above it has recorded the new pointer and master has it.
Shortcut: scripts/content-sync.sh
The mechanical steps are scripted. Commits stay manual, because the script never runs git commit.
cd lossless-monorepo/site
scripts/content-sync.sh # status: every repo in the chain (branch, dirty, ahead/behind, dev==main==master)
scripts/content-sync.sh pull # step 4: fast-forward src/generated-content + content-areas
scripts/content-sync.sh promote <path> # step 3: FF origin/main + origin/master to origin/development, refuses otherwise
promote takes a filesystem path, not a repo name. From site/, the whole chain is:
scripts/content-sync.sh # status
# 1–2. commit + push by hand: content/content-areas, then content/
scripts/content-sync.sh promote ../content/content-areas # 3.
scripts/content-sync.sh promote ../content # 3.
scripts/content-sync.sh pull # 4.
git add src/generated-content && git commit && git push origin development # 5.
# wait for the Vercel preview of that commit to pass, then:
scripts/content-sync.sh promote . # 5. → production
Start and finish with status. Every line should read clean and in parity.
The flow
1. Commit and push each content submodule
cd lossless-monorepo/content
# for each path listed in .gitmodules:
cd content-areas # then projects/Water-Template-CE, etc.
git switch development # make sure you're on a branch, not a detached HEAD
git add -A && git commit && git push origin development
Visit each submodule by hand. Don’t use git submodule foreach --recursive or git submodule update --recursive. update checks out the pinned SHA as a detached HEAD, so the next commit lands on no branch and the push goes nowhere useful.
2. Commit and push the content repo
cd lossless-monorepo/content
git add -A # includes the bumped submodule pointers
git commit && git push origin development
3. Bring development / main / master to parity, in every repo touched
Do this in each content submodule, in content, and later in site:
git fetch origin
git merge-base --is-ancestor origin/main origin/development && \
git merge-base --is-ancestor origin/master origin/development && \
git push origin development:main development:master
Fast-forward only. If either check fails, main or master has commits that development doesn’t. Stop and reconcile by hand; never force-push. The pushes are by refspec, so stale local main/master branches don’t matter.
4. Pull into the site’s copy of the content
cd lossless-monorepo/site/src/generated-content
git switch development && git pull --ff-only origin development
# then each nested submodule the site renders:
cd content-areas
git switch development && git pull --ff-only origin development
cd ..
git status # should be clean: the gitlink matches what content/ recorded
If a nested submodule folder is empty, it was never initialized. Run git submodule update --init <path> once, then git switch development inside it before pulling.
5. Commit and push the site, then promote
cd lossless-monorepo/site
git add src/generated-content
git commit -m "chore(submodule): bump generated-content to <sha>"
git push origin development
# then step 3 again in site/, to reach main and master
Why each step matters
- Production builds from
master. A push todevelopmentproduces a Vercel preview only. lossless.group doesn’t change untilsite/mastermoves. - Vercel clones the site’s submodules from their remotes. Anything unpushed at any level can’t be fetched at build time. The
prebuildscript also runs a non-fatalsubmodule update --init content-areasinsidegenerated-content. If that fails,/content-areasbuilds empty rather than failing. site/src/generated-contentis a separate clone oflossless-content. Pushing fromcontent/does nothing to it until it’s pulled.client-contentis private and stays uninitialized in the site’s copy. Moved out of the public repo on 2026-10-09, so/client/*builds empty.content-sync.sh pulluses--no-recurse-submodules, because an on-demand fetch into this submodule aborts the pull.projects/Water-Template-CEis not initialized in the site’s copy. Theprojectscollection globsprojects/**, so initializing it would start rendering that repo’s markdown. Make that a deliberate decision, not a side effect of this flow.
Checks before calling it done
# every repo in the chain: clean tree, and development == main == master on origin
git status --short
git rev-parse origin/development origin/main origin/master
Then confirm on production (e.g. curl -sI https://www.lossless.group/content-areas), not just on the preview URL.