docs: add git submodules hook recipe

README.md

@@ -19,7 +19,7 @@ Inspired by [haacked/dotfiles/tree-me](https://github.com/haacked/dotfiles/blob/
 - **Interactive selection menus** with fuzzy matching for checkout, remove, pr, and mr commands
 - GitHub PR support via `wt pr` command (uses `gh` CLI) — checks out the PR's actual branch name
 - GitLab MR support via `wt mr` command (uses `glab` CLI) — checks out the MR's actual branch name
-- **Pre/post command hooks** — run custom scripts on create/checkout/remove (e.g. [launch AI assistants](docs/examples.md#ai-assistants-and-editors), [share build caches](docs/examples.md#shared-build-cache-across-worktrees), [assign dev server ports](docs/examples.md#deterministic-dev-server-port-per-worktree), [copy `.env`](docs/examples.md#copy-env-to-new-worktrees))
+- **Pre/post command hooks** — run custom scripts on create/checkout/remove (e.g. [launch AI assistants](docs/examples.md#ai-assistants-and-editors), [share build caches](docs/examples.md#shared-build-cache-across-worktrees), [assign dev server ports](docs/examples.md#deterministic-dev-server-port-per-worktree), [copy `.env`](docs/examples.md#copy-env-to-new-worktrees), [init submodules](docs/examples.md#git-submodules-in-worktrees))
 - **Stale worktree detection** — find worktrees with deleted remote branches or inactive commits (`wt cleanup --stale`)
 - **Color-coded status output** — green (clean), red (dirty), yellow (ahead/behind), bold cyan (current); respects `NO_COLOR=1` and auto-strips colors when piped
 - **CI/CD status integration** — `wt status --ci` shows pipeline status (✓/✗/●) per branch via `gh` or `glab` CLI

docs/examples.md

@@ -136,6 +136,20 @@ wt create main
 
 If the referenced environment variable is not set, `wt` will return an error.
 
+## Git submodules in worktrees
+
+Git worktrees don't automatically initialize submodules. Use a hook to handle this:
+
+```toml
+[hooks]
+post_create = ["cd $WT_PATH && git submodule update --init --recursive"]
+post_checkout = ["cd $WT_PATH && git submodule update --init --recursive"]
+```
+
+This works well when all branches use the same (or similar) submodule commits — which is the common case.
+
+> **Caveat:** All worktrees share a single `.git/modules/` directory. If two worktrees pin the **same submodule to different commits**, running `git submodule update` in one worktree will move the shared checkout, making the submodule appear dirty in the other worktree. This is a [known git limitation](https://git-scm.com/docs/git-worktree#_bugs), not specific to wt. If your branches frequently diverge on submodule versions, consider using separate clones (`git clone`) instead of worktrees for that repo.
+
 ## Deterministic dev server port per worktree
 
 When running multiple worktrees simultaneously, each dev server needs a unique port. Use a post-checkout hook to compute a deterministic port offset from the branch name: