GIT · WORKTREE · MERGE

Git Worktree、分支合併、
Claude 記憶文件到底是什麼？

12 個 worktree、1 個沒合併的支線、2 套各自獨立的記錄系統。
用白話文 + 樹狀圖，把 Thomas 剛才搞混的概念一次理清。

① 前言：我搞混了什麼 ② 英文術語卡片 ③ PROGRESS.md vs worktree-log ④ 合併到底是什麼 ⑤ Thomas 實戰三步 ⑥ 文件 ≠ 記憶 ⑦ FAQ
1
我到底搞混了什麼？
TL;DR — 一頁看懂
  1. PROGRESS.md 是「專案成果」，進 git 被追蹤，是給人看的正式文檔。
  2. worktree-log 是「便條紙」，不進 git，只給Claude 冷啟動秒懂用途。
  3. 「合併 tree 到 master」不是搬資料夾，是把支線的 commit（改動記錄）接到主幹歷史線上。
  4. 合併完才能安全刪 tree，沒合併就刪 = commit 變孤兒、改動消失。
  5. 文件系統（git 追蹤）和記憶系統（.claude/）各走各的路，git 合併不會動記憶。

Thomas 剛才在 D:\Backup\Downloads 處理 12 個 worktree，做了一輪 git merge → worktree remove → branch -D，做完了心裡還有幾個問號：

這頁就是把這 4 個問題一次講清楚。

2
英文術語卡片（滑鼠停上去看解釋）

這些是接下來會反覆出現的詞。不用背，滑到不懂再停下來看即可。

repo / repository
倉庫
程式碼倉庫。一個被 git 管理的資料夾，裡面存了所有檔案 + 所有歷史改動記錄。根目錄有個 .git/ 隱藏資料夾，那就是它的大腦。
commit
提交 / 存檔
一次存檔。把當前改動打包，附上一段訊息，蓋個時間戳，變成歷史線上的一個點。每個 commit 有獨立的 ID（一串英數）。
branch
分支
歷史線的支線。本質上是「指向某個 commit 的書籤」。可以從主線分岔出去、自己做幾個 commit、再合併回來。
master / main
主幹分支
預設主幹。大部分 repo 預設分支叫 master（舊）或 main（新）。其他分支都是從它長出來的支線。
HEAD
當前位置指針
你現在站在哪。像遊戲裡的「當前存檔位置」箭頭。切分支時 HEAD 跟著移動。
worktree
工作樹 / 分身
git 的分身資料夾。同一個 repo 可以開多個並行工作區，每個放在不同資料夾、各自停在不同 branch。省去反覆切換分支的麻煩。
merge
合併
把兩條歷史線接起來。常見做法是把支線的改動合回 master，使 master 吸收那些 commit。
merge base
共同祖先
兩條線的分岔點。合併時 git 會往回找，兩條分支最後一次在一起的那個 commit，就是 merge base。
fast-forward
快進合併
主幹沒動、支線往前跑。這種情況 git 直接把 master 指針往前推到支線頂端，不產生「合併點」。歷史線看起來是一條直線。
--no-ff
產生合併點
強制產生 merge commit。即使可以快進，也留下一個合併點 M。好處是歷史線上清楚看到「這裡合併過一個支線」。Thomas 今天用的就是這種。
detached HEAD
離線頭
HEAD 沒掛在任何 branch 上。直接 checkout 到某個 commit ID 就會進這狀態。這時做的 commit 沒 branch 保護，一切換走就變孤兒。
orphan commit
孤兒提交
沒有 branch 指著的 commit。git 定期回收沒人引用的 commit（垃圾回收），所以孤兒 commit 會慢慢消失。
3
PROGRESS.md vs worktree-log：兩種完全不同的文件

這是 Thomas 剛才最混淆的一點：「這兩個 md 檔案不是差不多嗎，為什麼一個要合併一個不用？」

答案：它們根本是兩套獨立系統。

📘 PROGRESS.md（成果文檔）
  • 放在 worktree 的專案資料夾裡
  • 被 git 追蹤，會進 commit
  • 寫完 git add + commit 才算完事
  • 給人看的：總結做了什麼、為什麼這樣做
  • 會進入歷史線、永久存在
  • 合併到 master 後，master 也會有這份檔案
VS
📝 worktree-log（便條紙）
  • 放在 .claude/worktree-logs/
  • 不進 git（.gitignore 或根本不在 repo 裡）
  • 改完存檔就完事，沒 commit 這回事
  • 給 Claude 看的：這 tree 是幹嘛的、當前狀態
  • tree 刪了這檔也可以跟著刪，用完即棄
  • 跟 merge 完全無關
📌 類比
PROGRESS.md 像是「專案結案報告」，要歸檔、要交付、要進公司檔案庫（= git 歷史）。
worktree-log 像是「桌上便利貼」，寫「這隔間是做 X 項目的，現在進度 70%」，貼給下一個接手的同事看。工作結束就撕掉，不進檔案庫。
💡 關鍵差別

一個是成果，一個是便條；

一個永久、會被所有拉這個 repo 的人看到，一個用完即棄、只活在本機 .claude/ 裡。

所以今天做的操作：只需要把 PROGRESS.md 這類被 git 追蹤的檔案合併進 master。worktree-log 從頭到尾沒進 git，不需要也不能被「合併」。

4
「合併 tree 到 master」到底是什麼意思？

常見誤解：「合併 = 把資料夾搬進主資料夾」。不對。

正確理解：合併是把支線的 commit（改動記錄）接到主幹歷史線上。資料夾不會動，改變的是「歷史線的形狀」。

🌳 樹狀圖看合併

A B C D M 合併點 X （新增 PROGRESS.md） master branch → HEAD 合併前 → 合併後：歷史線的形狀變了 A─B─C─D 是主線，X 是支線的 commit，M 是合併點
合併後 master 的最新位置是 M；M 同時連到 D 和 X，主線「吸收」了支線的改動。

🔑 三個關鍵認知

1

合併改變的是「歷史線」，不是資料夾位置

資料夾 sharp-brown/ 從頭到尾都在原處，沒被搬進 Downloads/ 主 repo。改變的是：master 分支現在指向 M，而 M 的「祖先」包含了支線的 commit X。

2

合併後，master 的「檔案內容」才會多出支線的檔案

因為 X 這個 commit 有「新增 PROGRESS.md」這個動作，合併後 master checkout 出來的工作目錄，自然也就有 PROGRESS.md 了。

3

--no-ff 強制產生合併點 M

如果不加 --no-ff，在「master 沒前進、支線單獨跑」的情況下，git 會快進：直接把 master 指針從 D 推到 X，不產生 M。歷史線變成直的。
加 --no-ff 就算能快進也強制產生 M，歷史上留下「這裡合併了一個支線」的明顯記號，日後好追蹤。

⚠️ 為什麼合併完才能安全刪 tree？

沒合併就刪 = commit 變孤兒。branch 刪掉 = 支線的「書籤」沒了，X 這個 commit 沒人指著，就變成 orphan commit，git 一做垃圾回收（gc）就真的消失了。

合併後刪 = 安全。支線的 commit X 已經被 M 這個合併點「收編」進 master 的歷史鏈，就算 branch 書籤刪掉、worktree 資料夾刪掉，master 鏈條上還留著 X 的身影，PROGRESS.md 永遠找得回來。

5
Thomas 今天的實戰三步

背景：D:\Backup\Downloads 是個 repo，裡面有 12 個 worktree。其中 sharp-brown/ 這個 tree 在 branch claude/2026-04-10-desktop-cc-questions 上，比 master 多 1 個 commit（新增 PROGRESS.md 183 行）。目標：把這 1 個 commit 吸收進 master，然後清掉 tree 和 branch。

📋 完整命令序列

# 1️⃣ 站到 master（主 repo 目錄）
cd D:/Backup/Downloads
git checkout master

# 2️⃣ 把支線合併進來（產生合併點 M）
git merge --no-ff claude/2026-04-10-desktop-cc-questions \
  -m "merge sharp-brown: add PROGRESS.md"

# 3️⃣ 移除 worktree 資料夾（git 層面的清理）
git worktree remove sharp-brown

# 4️⃣ 刪掉 branch 書籤（支線已被吸收，書籤無用）
git branch -D claude/2026-04-10-desktop-cc-questions
📌 三步白話翻譯
Step 2（merge）：跟主幹說「請把支線那 1 筆改動納入正史」
Step 3（worktree remove）：把分身工作間的門鎖上、拆掉
Step 4（branch -D）：把「支線書籤」丟進垃圾桶——反正支線的 commit 已經在主幹鏈上了，書籤沒用了

🎯 這之後發生了什麼

6
文件系統 vs 記憶系統：各走各的路

最後釐清這個重要區分：剛才的 git 合併完全沒動到 Claude 記憶。

📁 文件系統（git 管轄）
  • PROGRESS.md、程式碼、設定檔
  • 被 git add 追蹤
  • 進 commit、上 GitHub
  • 合併時會搬動
  • 給人看、給程式跑
≠
🧠 記憶系統（.claude/）
  • MEMORY.md、worktree-log.md、CLAUDE.md
  • 在 .claude/ 資料夾下
  • 通常被 .gitignore 排除
  • 合併時動不到
  • 給 Claude 冷啟動讀
🎯 重點 take-away

今天做的 git merge → worktree remove → branch -D，三步都只動 git 管轄的文件。

Claude 的記憶（MEMORY.md、worktree-log）自己獨立一套，git 操作不會碰它們。要更新記憶得另外開 Claude、用對應工具。

兩套系統互不交叉：文件是「實體成果」，記憶是「AI 的燃料」。別把它們混為一談。

7
FAQ
Q1：我合併完，worktree-log 裡那筆「sharp-brown 用途記錄」還要留著嗎？
不用了。worktree 刪了，對應的 worktree-log 也該順手刪——它的使命就是「幫下一個 session 秒懂這 tree 在幹嘛」，tree 都沒了，筆記自然沒意義。建議把狀態先改成「✅ 已合併並清理」，存檔存個幾天做 log 用，之後再刪。
Q2：我沒合併就直接 worktree remove 了，怎麼救？
只要 branch 還在，就能救。git worktree remove 只是拆資料夾，branch 書籤還指著 X，X 還活著。重新開一個 worktree 到同 branch（git worktree add 路徑 分支名）就能拿回檔案。
但如果已經 branch -D 把 branch 也刪了，就要靠 git reflog 在 30 天內找 commit ID，過了 gc 就真沒了。
Q3：fast-forward 和 --no-ff 到底該用哪個？
短期實驗、沒歷史意義的支線 → fast-forward 更乾淨，歷史線是一條直線。
有里程碑意義、日後可能要回看「這波改動整體做了什麼」→ 用 --no-ff 留下合併點。Thomas 今天的 PROGRESS.md 算成果交付，用 --no-ff 對的。
Q4：一個 repo 可以開幾個 worktree？
技術上沒上限，常見 3–10 個。Thomas 開到 12 個算多了但正常。每個 worktree 獨佔一個 branch（不能兩個 worktree 都 checkout 同一個 branch）。用 git worktree list 看目前有哪些。
Q5：為什麼不直接 rm -rf sharp-brown/？要用 git worktree remove？
因為 git 在主 repo 的 .git/worktrees/ 裡有註冊表記錄「我派了一個分身叫 sharp-brown，在路徑 X」。直接 rm -rf 會留下失效註冊項，git worktree list 會出現殘影。必須用 git worktree remove（或之後 git worktree prune）來清註冊表。
Q6：detached HEAD 跟今天的操作有關嗎？
沒直接關係。但如果你 git checkout 某個commit ID（不是 branch 名），就會進 detached HEAD。在這狀態下做的 commit 沒 branch 保護，一切走就變孤兒。今天操作全程都在有 branch 的狀態，安全。
Q7：所以我以後看到 tree 資料夾，就知道它是可以動的「分身工作間」？
對。worktree 資料夾不是獨立 repo，它是主 repo 的一個分身，共用同一個 .git/（主 repo 裡的那個）。所以所有 git 操作其實都是在動主 repo 的歷史，worktree 只是給你一個乾淨的工作目錄而已。
① 前言 ② 詞彙表 ③ 兩種文件 ④ 合併 ⑤ 實戰 ⑥ 文件≠記憶 ⑦ FAQ ← 返回首頁 ↑ 回到頂部