Skip to main content

Git Subtree Guide

Use this when importing or synchronizing external repositories into this monorepo while preserving commit history.

Why Subtree​

  • preserves history inside monorepo paths
  • simpler day-to-day workflow than submodules for this repo style
  • allows later sync with original repositories when needed

Initial Import (Examples)​

Import query-builder into apps/query-builder​

git remote add query-builder git@github.com:albertorcf/query-builder.git
git fetch query-builder
git subtree add --prefix=apps/query-builder query-builder main -m "import(query-builder): add as subtree"

Import ai-rag-agent into apps/ai-rag-agent​

git remote add ai-rag-agent git@github.com:albertorcf/ai-rag-agent.git
git fetch ai-rag-agent
git subtree add --prefix=apps/ai-rag-agent ai-rag-agent main -m "import(ai-rag-agent): add as subtree"

Sync from Upstream Repositories​

git fetch query-builder
git subtree pull --prefix=apps/query-builder query-builder main -m "sync(query-builder): subtree pull"

git fetch ai-rag-agent
git subtree pull --prefix=apps/ai-rag-agent ai-rag-agent main -m "sync(ai-rag-agent): subtree pull"

Optional: Push Back to Upstream​

git subtree push --prefix=apps/query-builder query-builder main

Important Notes​

  • subtree pull/push requires the remote to still exist.
  • You can archive old repositories later when monorepo becomes the only source of truth.
  • To inspect imported history: git log -- apps/query-builder