When to Use Which

When to Use Which

After this page you can pick submodule, worktree, or neither for a desk problem.

Worktree

Use a worktree when one repository needs two checkouts: a hotfix while a feature is dirty, a PR review, a tag build. Same remotes, same hooks, cheap on Linux disk.

Submodule

Use a submodule when two repositories must stay separate histories, with the parent pinning a commit of the child: a shared library, a firmware blob, a docs site with its own release train.

Copy the files

If desk-lib is three Python files and only desk-api uses them, put them in desk-api. Submodule overhead is real.

Monorepo

If desk-web, desk-api, and desk-infra always change together, one repository with three directories may be simpler (chapter 15). Worktrees still apply (two branches of the monorepo). Submodules do not.

Extra clone

git clone to a second path is fine for a throwaway experiment you might delete with rm -rf. You duplicate objects until git gc. Worktree is cleaner for a second branch.

Extra remote

Two forges is remotes (chapter 11), not submodules. Push the same history twice.

Rule of thumb

Same project, two directories → worktree. Two projects, one pin → submodule. Two projects, always in lockstep → one repo.

 one repo, two checkouts     ──►  worktree
 two repos, pin a commit     ──►  submodule
 two repos, always together  ──►  one monorepo
 two forges, same history    ──►  extra remote