docs(solutions): compound refresh — fix reference drift, grow CONCEPTS.md
Refresh audit of all 13 docs/solutions learnings against the current codebase. Core guidance verified accurate everywhere; three docs had reference drift: - dual-repo-submodule-workflow: point worktree setup/teardown at the make worktree-new/worktree-rm targets (manual procedure misses .worktree-env isolation) - docker-exec-root-owned-bind-mount-files: tracked-plugin list now includes entry-actions; fix-perms description matches actual target - grav-plugin-config-without-code-wont-enable: 3-category model's custom-in-repo list now includes entry-actions CONCEPTS.md: add Container, Content repo, Outer repo, Pin, Env tree, Remote-only plugin; refresh Active Trip (switching is one setting now). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0195b3cDdMeize2Mm1FgC2aU
This commit is contained in:
@@ -56,33 +56,28 @@ Production is unaffected either way: prod pulls `user/` directly via the content
|
||||
|
||||
The payoff. Because `docker-compose.yml` mounts `./user` **relative to the compose file**, and a worktree is a full copy of the outer tree (compose file included), each worktree serves *its own* `user/`. Two worktrees = two independent sites, no gitlink collisions.
|
||||
|
||||
Set up a feature worktree off `main`:
|
||||
**Use the make targets — don't do the steps by hand.** From the main checkout:
|
||||
|
||||
```bash
|
||||
# outer worktree on a new feature branch
|
||||
git worktree add .worktrees/<feature> -b feat/<feature> main
|
||||
cd .worktrees/<feature>
|
||||
|
||||
# populate user/ at the pinned SHA, then branch it for the cross-repo work
|
||||
git submodule update --init user
|
||||
git -C user checkout -b feat/<feature>
|
||||
|
||||
# its own dev server — separate project name + port from the main checkout's :8081
|
||||
docker compose -p itte-<feature> up -d
|
||||
make worktree-new NAME=<feature> # create + start its own dev server
|
||||
make worktree-rm NAME=<feature> # tear down cleanly
|
||||
```
|
||||
|
||||
`worktree-new` does, in order: `git worktree add .worktrees/<feature> -b feat/<feature> main`, `git submodule update --init user`, branches `user/` onto `feat/<feature>`, writes a git-ignored `.worktree-env` (own compose project name, container name, auto-assigned port `8090+`) so every `make`/compose command run inside that worktree targets its own server, and starts the Grav service. The manual equivalent misses `.worktree-env` — without it, make commands in the worktree hit the main checkout's container on `:8081`.
|
||||
|
||||
`.worktrees/` is kept out of git via `.git/info/exclude` (local, shared across worktrees — no committed `.gitignore` change needed).
|
||||
|
||||
### Teardown
|
||||
|
||||
A submodule inside a linked worktree stores its git dir under `.git/modules/user/worktrees/<name>`, so removing the outer worktree needs a second cleanup step:
|
||||
A submodule inside a linked worktree stores its git dir under `.git/modules/user/worktrees/<name>`, so teardown needs a submodule-deinit step before the worktree can be removed — skipping it is what leaves orphaned `.worktrees/` dirs. `make worktree-rm NAME=<feature>` runs the full sequence:
|
||||
|
||||
```bash
|
||||
docker compose -p itte-<feature> down
|
||||
cd "$(git rev-parse --show-toplevel)" # back to the main checkout
|
||||
git -C .worktrees/<feature> submodule deinit user # detach the submodule worktree
|
||||
git worktree remove .worktrees/<feature> # remove the outer worktree
|
||||
git branch -d feat/<feature> # if merged
|
||||
# what worktree-rm does internally
|
||||
make -C .worktrees/<feature> stop # compose down (its own server)
|
||||
git -C .worktrees/<feature> submodule deinit -f user # detach the submodule worktree
|
||||
git worktree remove --force .worktrees/<feature>
|
||||
git worktree prune
|
||||
git branch -d feat/<feature> # manual, if merged
|
||||
```
|
||||
|
||||
### Landing a commit on main without disturbing the main checkout
|
||||
|
||||
Reference in New Issue
Block a user