Architecture

Use Git Submodules and Subtrees Deliberately

Choose a repository composition model for shared code and external dependencies with clear update ownership.

Submodules and subtrees allow one repository to include code maintained elsewhere, but they introduce different update and collaboration behaviors.

Understand submodules

A submodule records a specific commit from another repository. The parent repository does not automatically contain the submodule's full working history. Contributors must initialize and update it, and deployment tooling must understand the pinned revision.

Submodules are useful when the dependency should remain independently versioned and maintained.

Understand subtree workflows

A subtree brings another repository's content into a directory in the parent repository. It can simplify cloning and deployment but may make synchronization and contribution flow less obvious.

Consider alternatives

For libraries, a package manager may provide better versioning and dependency metadata. For tightly coupled code, a monorepo may be simpler. Avoid adding repository composition complexity merely to share a small number of files.

Checklist

  • Define who owns and updates the shared code.
  • Document clone and update procedures.
  • Pin and review external revisions.
  • Consider package managers or monorepos.
  • Test CI and deployment with the chosen model.
Share this page Help other developers discover this resource.