🧩 Multi-Folder Git Subtree Sync

Multi-Folder Git Subtree Sync

Git Subtrees let you share multiple folders (like src/components, docs, and scripts) across different repositories.
Resources can be organized inside folders (recommended for clarity) or placed at the root of the shared repo.
Both approaches work — the key is to use the correct --prefix path when adding the subtree.

---

🧩 Shared Repository Structure Options

Organized in Folders

shared-resources/
├── src/components/
│   ├── Button.tsx
│   ├── Navbar.tsx
├── docs/
│   ├── getting-started.md
│   ├── api-reference.md
└── scripts/
    ├── build.sh
    ├── deploy.sh

Files at Root

shared-resources/
├── Button.tsx
├── Navbar.tsx
├── getting-started.md
├── api-reference.md
├── build.sh
└── deploy.sh

---

🪜 Setup Steps

Add Remote

git remote add shared https://github.com/ruseleredu/docusaurus-shared.git

Add Subtrees

If resources are in folders:

git subtree add --prefix=src/components shared main --squash
git subtree add --prefix=docs shared main --squash
git subtree add --prefix=scripts shared main --squash

If resources are at root:

git subtree add --prefix=. shared main --squash

Pull Updates

git subtree pull --prefix=src/components shared main --squash
git subtree pull --prefix=docs shared main --squash
git subtree pull --prefix=scripts shared main --squash

Or, if root:

git subtree pull --prefix=. shared main --squash

Push Changes

git subtree push --prefix=src/components shared main
git subtree push --prefix=docs shared main
git subtree push --prefix=scripts shared main

Or, if root:

git subtree push --prefix=. shared main

---

📊 Workflow Overview

Setup	Pros	Cons
Folders	Clear separation of components, docs, scripts	Slightly more commands to manage
Root	Simpler if only a few files	Can get messy with many mixed resources

---

✅ Best Practices

• Prefer folders for clarity and scalability.
• Use --squash to keep history clean.
• Document the workflow in your site’s README so teammates know how to sync.
• Always pull before pushing to avoid conflicts.

Sharing a Single File with Git Subtree

Git Subtree works at the directory level, but you can still share a single file by either:

• Placing it inside a dedicated folder (recommended for scalability).
• Keeping it at the root of the shared repo.

---

🧩 Shared Repository Structure Options

File Inside Folder

shared-resources/
└── scripts/
    └── deploy.sh

File at Root

shared-resources/
└── deploy.sh

---

🪜 Setup Steps

Add Remote

git remote add shared https://github.com/your-org/shared-resources.git

Add Subtree

If file is inside a folder:

git subtree add --prefix=scripts shared main --squash

If file is at root:

git subtree add --prefix=deploy.sh shared main --squash

Pull Updates

Folder:

git subtree pull --prefix=scripts shared main --squash

Root:

git subtree pull --prefix=deploy.sh shared main --squash

Push Changes

Folder:

git subtree push --prefix=scripts shared main

Root:

git subtree push --prefix=deploy.sh shared main

---

📊 Comparison

Setup	Command	Best Use Case
Folder	git subtree add --prefix=scripts shared main --squash	When you may add more files later
Root	git subtree add --prefix=deploy.sh shared main --squash	When you only need one file

---

✅ Best Practices

• Use a folder if you expect to add more shared files later.
• Root setup is fine for truly single‑file sharing.
• Always pull before pushing to avoid conflicts.
• Use --squash to keep history clean.