How To Use `Git Subtree` To Add A 3rd Party Repository Into A Subfolder Of Your Repo (And The Difference Between `Git Submodule` Vs. `Git Subtree`)

how-to-git-subtree.md

How To Use Git Subtree To Add A 3rd Party Repository Into A Subfolder Of Your Repo (And The Difference Between Git Submodule Vs. Git Subtree)

This guide shows how to add external documentation or code as a subtree while keeping your main repository's origin pointing to your own repo.

For a New Repository

# 1. Initialize your repository
git init

# 2. Create initial commit (required for subtree)
echo "" > .gitkeep
git add .gitkeep
git commit -m "Initial commit"

# 3. Add YOUR repository as origin
git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO.git

# 4. Add the 3rd party repo as a separate remote (just for subtree operations)
git remote add drizzle-docs https://github.com/drizzle-team/drizzle-orm-docs.git

# 5. Add the 3rd party content as a subtree
git subtree add --prefix=drizzle-docs drizzle-docs main --squash

# 6. Push to YOUR repository
git push -u origin main

For an Existing Repository

# 1. Add the 3rd party repo as a separate remote (just for subtree operations)
git remote add drizzle-docs https://github.com/drizzle-team/drizzle-orm-docs.git

# 2. Add the 3rd party content as a subtree
git subtree add --prefix=drizzle-docs drizzle-docs main --squash

# 3. Commit is created automatically by subtree add

Understanding the Remotes

• origin: Points to YOUR repository (where you push your code)
• drizzle-docs: Points to the 3rd party repository (only used for subtree pull operations)

You can verify your remotes:

git remote -v

Updating Documentation

To pull the latest changes from the upstream Drizzle documentation:

git subtree pull --prefix=drizzle-docs drizzle-docs main --squash

This will fetch any updates from the original Drizzle documentation and merge them into your drizzle-docs folder.

Git Subtree vs Git Submodule

Git Submodule

# Add as submodule
git submodule add https://github.com/drizzle-team/drizzle-orm-docs.git drizzle-docs

# After cloning
git submodule update --init

Characteristics:

• Stores only a reference (commit SHA) to the external repo
• drizzle-docs folder appears empty until you run git submodule update --init
• Team members must know to run submodule commands
• Shows as a special directory entry in git (not regular files)
• Updates require updating the submodule then committing the new reference

Git Subtree (what we're using)

# Add as subtree
git subtree add --prefix=drizzle-docs drizzle-docs main --squash

Characteristics:

• Copies all files directly into your repository
• drizzle-docs folder contains actual files immediately
• Team members get everything with regular git clone - no extra steps
• Files appear as normal files in your repository
• Updates are merged directly into your repository history

Why Subtree for Documentation?

1. Simplicity: Team members don't need to learn submodule commands
2. Reliability: No broken references or missing content
3. Self-contained: Your repo has everything it needs
4. Searchable: All docs are indexed with your code
5. Permanence: If Drizzle deletes their repo, you still have all the files

Critical Difference: What Happens if the External Repo Disappears?

Submodule: You lose access to the content! Your repo only stores a reference, so if Drizzle deletes their repo:

• New clones fail at git submodule update
• You can't access the documentation anymore
• Your repo is broken

Subtree: You keep everything! Since files are copied into your repo:

• All content remains in your repository forever
• New clones work perfectly
• You're completely independent