From 8da0a7fc701ba2440f093d68f447e0e48cb618f8 Mon Sep 17 00:00:00 2001 From: Tim Van Wassenhove Date: Fri, 3 Apr 2026 21:32:43 +0200 Subject: [PATCH] docs: add git submodules hook recipe with caveat Add example hook for auto-initializing submodules in new worktrees, with a note about the shared .git/modules caveat when branches pin different submodule commits. --- README.md | 2 +- docs/examples.md | 14 ++++++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a725e4a..cd62373 100644 --- a/README.md +++ b/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 diff --git a/docs/examples.md b/docs/examples.md index 80568f7..381b14f 100644 --- a/docs/examples.md +++ b/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: