Git Subtree

Git Subtree 是另一種在專案中嵌入其他 Git 倉庫的方式，相比 Submodule 更容易使用。

建立共用 repo

這個 repo 存放多專案共用的資源（例如 .claude/skill）：

mkdir claude-skill
cd claude-skill
git init
mkdir skill
echo "echo 'Hello from skill'" > skill/demo.sh
git add .
git commit -m "initial commit of skill"
git branch -M main
git remote add origin https://github.com/your-org/claude-skill.git
git push -u origin main

共用 repo 建立完成，供其他專案 pull/push。這裡的 skill/ 是 repo 內的目錄，之後會對應專案內的 .claude/skill。

在專案 A 建立 Git

mkdir project-A
cd project-A
git init
git remote add origin https://github.com/your-org/project-A.git
git branch -M main
git add .
git commit -m "initial commit for project-A"
git push -u origin main

origin → 專案本身的遠端
接下來要把 subtree 合併進專案

加入 Subtree

# 1. 新增遠端共用 repo
git remote add claude https://github.com/your-org/claude-skill.git
git fetch claude

# 2. 合併 subtree
git subtree add --prefix=.claude/skill claude main --squash

參數說明

參數	說明
`--prefix=.claude/skill`	專案內放置 subtree 的目錄
`claude`	遠端名稱（不是 URL），告訴 Git 哪個 repo
`main`	遠端分支或 commit，要拉取哪個分支
`--squash`	把 subtree commit 壓縮成單一 commit（保護專案歷史）

結果

project-A/
 └─ .claude/
      └─ skill/
           └─ demo.sh

現在專案 A 可以直接使用 .claude/skill 裡的內容。

更新 Subtree

從共用 repo 拉取新內容：

cd project-A
git fetch claude
git subtree pull --prefix=.claude/skill claude main --squash

這會把遠端最新內容更新到 .claude/skill。

原理：fetch 遠端 → 合併到專案目錄 → 壓縮 commit

專案修改後推回共用 repo

如果在專案 A 修改了 .claude/skill，想同步回 claude-skill：

git subtree push --prefix=.claude/skill claude main

參數	說明
`push`	把專案內的 subtree 修改推回遠端
`--prefix`	指定專案內的 subtree 目錄
`claude`	遠端名稱
`main`	推回遠端分支

多專案共用

在專案 B 同樣操作：

git remote add claude https://github.com/your-org/claude-skill.git
git fetch claude
git subtree add --prefix=.claude/skill claude main --squash

操作流程與專案 A 一樣，更新共用 repo 或推回都用相同指令。

常用 Subtree 指令總結

功能	指令	說明
加入 subtree	`git subtree add --prefix=.claude/skill claude main --squash`	專案首次合併共用 repo
拉取更新	`git subtree pull --prefix=.claude/skill claude main --squash`	從共用 repo 更新專案內 subtree
推回修改	`git subtree push --prefix=.claude/skill claude main`	把專案修改回傳到共用 repo

Submodule vs Subtree

特性	Submodule	Subtree
Clone 方式	需要額外 `--recurse-submodules`	直接 clone 即可
更新方式	兩層 commit	單一 commit
歷史記錄	分離的歷史	合併到專案歷史
適用場景	需要精確控制版本	簡單共用資源

Git Submodule