版本管理名字瞎寫：三個 refine, 和一堆 .DS_Store

本文是"Vibe Coding 覆盤手記"系列的第 3 篇，共 5 篇。

TLDR 四條 Git 規則能讓 vibe coding 項目少踩大部分坑：① 是 後的第一個文件——讓 AI 根據你的技術棧生成，10 秒搞定，否則 node_modules、.DS_Store、Excel 原始數據全部進倉庫，我的項目因此膨脹到 2.7 GB；② 用了 Git 就徹底放棄文件名後綴 、——一個文件一個名字，所有歷史交給 Git，想安全實驗就開 branch，兩套版本系統並行不是雙保險，是雙重混亂；③ 讓 AI 幫你寫 commit message——每次提交前說"幫我看看改了什麼，寫個提交說明"，30 秒生成一條具體信息，比三個連續的"refine"有用一萬倍；④ 在關鍵節點打 tag——評審版打 v0.5-first-review，最終版打 v1.0-final，之後 git diff v0.5..v1.0 一條命令精確對比，不用在 30 條提交記錄裏翻找。

項目做到第 20 天，我想回到"那個圖表顏色還沒改的版本"。打開 Git 歷史，看到三條連續的提交記錄：refine、refine、refine。它們之間有什麼區別？我不知道。當時的我也不知道(其實我一直有比較認真寫commit message,但那三個refine當時確實是懶了有點放棄治療的意思)。

三個 refine 並排站在那裏，像三扇一模一樣的門，後面是什麼只有打開才知道。而打開的方式是對每一個執行 git diff，逐行看代碼差異——對於一個 4000 多行的 HTML 文件來說，這基本等於大海撈針。

另一個困惑發生得更早。第一次運行 git status，終端輸出了一堆文件變更，其中有一個叫 .DS_Store 的文件顯示"被修改了"。我沒有改過任何叫這個名字的東西。我甚至不知道它是什麼。搜索之後才明白：這是 macOS 系統在你打開文件夾時自動生成的隱藏文件，記錄圖標排列方式之類的元數據。它和我的項目毫無關係，但 Git 在認真地跟蹤它的每一次變化。

這兩個困惑，一個關於"我寫了什麼 Git 不知道"，一個關於"Git 跟蹤了什麼我不知道"。它們指向同一個問題：我在用 Git，但我不真正理解 Git 應該怎麼用。

2.7 GB 的 Git 倉庫

項目覆盤時我做了一次倉庫體檢，結果大震驚。

Git 倉庫體積：2.7 GB。跟蹤的文件總數：2517 個。其中真正需要跟蹤的源代碼文件——notebook、HTML、CSS、腳本——大約 78 個，佔 3%。剩下的 97%，是不該出現在 Git 裏的東西。

這 97% 都有誰？

排名第一的是 node_modules，2243 個文件，佔了總數的將近九成。這是我在項目後期為了導出 PDF 安裝的一個 Node.js 工具包，運行 npm install 之後自動下載的依賴文件。這些文件可以隨時通過一條命令重新生成，不需要版本管理。更關鍵的是，它們包含大量二進制文件——瀏覽器引擎、編譯後的代碼——Git 根本無法展示它們的變化內容。

排名第二的是 29 個原始 Excel 數據文件，從 202403.xlsx 到 202602.xlsx，每個幾 MB 到幾十 MB。作為原始數據源，它們幾乎不會被修改，即使修改了，Git 也只能告訴你"文件變了"，看不到具體哪個單元格的數字從 54 變成了 55。

然後是 24 個導出的 PNG 截圖和 PDF 文件。這些都是腳本自動生成的產物，運行一次導出命令就能重新生成。

再就是前面提到的 .DS_Store。不止一個——項目裏每個文件夾都可能有一個。每次我在 Finder 裏隨便點開一個文件夾，它就會被"修改"，然後出現在 git status 裏，製造噪音。

還有幾個 Excel 臨時文件，文件名以 ~$ 開頭——這是 Excel 打開文件時自動創建的鎖定文件，關閉 Excel 就會消失。它們甚至不是我的文件，是軟件的臨時產物。

為什麼這些東西會被 Git 跟蹤？原因簡單到讓人尷尬：項目一開始沒有 .gitignore。

.gitignore 是一個放在項目根目錄下的純文本文件，作用只有一個——告訴 Git"哪些文件不要管"。它的寫法非常簡單：

# macOS 系統文件
.DS_Store

# Node.js 依賴
node_modules/

# 原始數據
data/raw_data_rednote/*.xlsx

# 導出產物
final-slides/exports/

就這麼幾行。每一行是一條規則，# 開頭的是註釋，* 是通配符，/ 結尾表示文件夾。把這個文件放在項目根目錄，Git 就會自動跳過匹配的文件，不跟蹤、不提交。

沒有 .gitignore 的後果很直接：倉庫臃腫到 2.7 GB，如果要克隆到另一台電腦需要下載全部內容；git status 每次都會列出大量無關文件的變更，真正有意義的代碼修改被淹沒在噪音裏；git add . 這種偷懶的全量添加命令會把所有不該進來的東西一起帶進來。

後來我在覆盤時補上了 .gitignore，效果立竿見影：Git 需要關注的文件從 2517 個降到了 173 個，減少了 93%。但遺憾的是，已經進入 Git 歷史的那些文件不會自動消失——它們永久留在了倉庫的歷史記錄裏，這就是為什麼 .git 文件夾依然有 2.7 GB。

教訓很清楚：.gitignore 不是項目做到一半才補的東西，它應該是 git init 之後創建的第一個文件。你甚至不需要自己寫——告訴 AI"我的項目用 Python + Node.js + macOS，幫我生成一個 .gitignore"，十秒鐘就能得到一個覆蓋全面的版本。

同時維護兩套版本系統

項目覆盤時，我打開 slides 文件夾，看到了這樣一個文件列表：

Color-Overview-20260402.html
Color-Overview-20260402-v2.html
Color-Overview-20260402-v3.html
Color-Overview-20260402-v4.html
Color-Overview-20260402-v5.html
Color-Overview-20260403.html
Color-Overview-20260403-v1.html
archive/

archive 文件夾裏裝的是更早的版本。

我其實知道用Git做版本管理就可以了，但還是忍不住給文件創建副本，這種非Github時代的古法文件災備思路，懂的都懂。這個項目有 30 次 Git 提交，也就是說 Git 已經在幫我記錄每一次修改的歷史。而我同時又在用文件名後綴 -v2、-v3、-v4 來管理版本，有一種既要又要的分裂的美。

兩套版本系統。這帶來了三個問題。

第一，想找回之前某個版本的時候，agent不知道該看 Git 歷史還是找文件名。-v3 和 -v4 之間的差別記錄在 Git 裏嗎？還是隻是手動複製了一份改了個名字？答案是兩種情況都有，這就很混亂。

第二，每個版本都是一份完整拷貝。我的 HTML 文件有 4000 多行，每創建一個 -v2、-v3，就是 4000 多行的全量複製。而 Git 也在跟蹤這些拷貝的每一次變更，倉庫體積成倍增長。

第三，AI 也會被搞糊塗。當我在一個新的 AI 對話中說"基於最新版本修改"，AI 需要先判斷哪個是最新的。20260403.html 和 20260403-v1.html 哪個更新？光看文件名無法確定。實際上我自己有時候也記不清。

正確的做法是隻維護一個文件，比如就叫 Color-Overview.html，所有版本歷史交給 Git 管理。想查看歷史？git log --oneline 列出所有提交記錄。想回到之前的版本？git checkout 加上對應的提交編號。想對比兩個版本的差異？git diff 精確到每一行代碼的變化。

如果擔心"改壞了回不去"——這恰好就是 Git 存在的意義。每一次提交都是一個完整的快照，任何時候都可以回到任何一個歷史版本。你甚至可以在大改之前創建一個分支：大膽實驗，效果好就合併回來，效果不好就扔掉分支，主線完全不受影響。

用文件名管版本是沒有 Git 之前的做法。一旦你開始用 Git，就應該徹底放棄 -v1、-v2 這套命名方式。兩套系統並行不是雙重保險，是雙重混亂。（除非有一些新舊版本的比較需求。但這種需求可以創建branch）

三個 refine

回到開頭的那個場景。我的 Git 提交記錄中有這樣一段：

f7e60bd preoject retro & QAs
17132e7 revision
91c1b54 refine
b7b15b9 refine & email draft
e939d34 refine
6fc0a77 add cover/end
2cdb53e 精裝修，no cover page

三個 refine 和一個 revision，幾乎佔了這段記錄的一半。兩天之後我想"回到那個圖表顏色還沒改的版本"，面對這些提交記錄完全無從下手。三個 refine 裏哪個改了圖表顏色？哪個改了文字？哪個調了間距？沒有任何線索。我只能一個一個 git diff 翻過去，在幾千行的差異中尋找和"圖表顏色"相關的那幾行改動。

提交說明（commit message）這件事，我一直知道它很重要，最好能寫清楚這次修改了什麼。但是人一懶起來真的是什麼都幹得出來，包括亂寫commit message. 像這次這種單人小項目還好，大項目這樣寫真的不行，完全是嫌自己日子太舒服，給回溯上難度，尤其在vibe coding的場景下。

第一，vibe coding 的迭代速度很快。AI 幫你寫代碼，一天可能產生 5 到 10 次提交。當提交密度這麼高的時候，每條記錄之間的差異變得很細微——也許只是調了一個間距、改了一個顏色、換了一段文字。如果提交說明都是 "refine"，這些細微的差異就完全淹沒在了一個籠統的詞裏。

第二，新開的 AI 對話不知道之前發生了什麼。當我在一個新的會話中說"幫我看看最近幾次提交都改了什麼"，AI 會去讀 git log。如果看到的是三個 "refine"，它和我一樣無法判斷該回退到哪個版本、哪次提交引入了某個問題。提交說明是 AI 瞭解項目歷史的主要途徑之一，寫得含糊，AI 的幫助也會變得含糊。

好的提交說明不需要多複雜。對比一下：

# 之前
refine
refine
refine

# 之後
style(1.2): 統一 Color 為 Colorway 術語
content(summary): 添加頁面結論文字
fix(2.2): 修正男裝聚類名稱

後者多花了十幾秒，但三個月後你依然知道每次改了什麼。前綴 style、content、fix 標記了修改類型，括號裏的 1.2、summary、2.2 標記了修改的頁面範圍，後面的中文描述是具體內容。不需要寫得很長，一句話概括就夠。

實際操作中，你甚至不需要自己想這句話。每次準備提交之前，對 AI 說一句"幫我看看這次改了什麼，寫一個提交說明"，它會根據代碼差異自動生成一條清晰的信息。整個過程不到 30 秒。

有人可能會說：我的項目就自己一個人做，提交說明寫給誰看？答案是寫給未來的自己看。兩週後的你、兩個月後的你、下一個項目開始時回來找參考的你——他們都會感謝今天多花 30 秒寫了一句有信息量的話，而不是一個 "refine"。

給重要時刻貼書籤

我的項目有 30 次提交，0 個 tag。

Tag 是什麼？如果把 Git 倉庫比作一本正在寫的書，commit 就是每一次按下保存鍵——你寫了一段、改了一段、刪了一段，每次保存都產生一條記錄。30 次提交，就像這本書被保存了 30 次。

Tag 是在某一頁貼一個便利貼書籤。你在第 15 次保存時覺得"這個版本可以拿去給老闆看了"，就在這個提交上貼一個標籤，叫 v0.5-first-review。書籤不會改變書的內容，它只是幫你快速翻到那一頁。

我的 30 次提交長這樣：

f7e60bd preoject retro & QAs
17132e7 revision
91c1b54 refine
b7b15b9 refine & email draft
e939d34 refine
6fc0a77 add cover/end
2cdb53e 精裝修，no cover page
57bf7eb 本地圖片嵌入
eb2b2a6 2.2 & 2.3 combined
06c49ed add data: secondary color cohort to excel

現在假設老闆問："從你第一次拿給我看到最終版，中間改了多少東西？"我得在這 30 條記錄裏找出哪條對應"第一次評審版"、哪條對應"最終版"。面對三個 refine 和一個"精裝修"，只能靠記憶——而記憶是最不可靠的版本管理工具。

如果當時打了 tag，情況完全不同。給 add cover/end 這條提交貼一個 v0.5-first-review，給最終版貼一個 v1.0-final，之後想對比兩個版本之間的差異，一條命令就夠：

git diff v0.5-first-review..v1.0-final

Git 會精確列出從評審版到最終版之間的所有代碼變化。不需要記住提交編號，不需要在 30 條記錄裏翻找，不需要猜"refine"是哪個 refine。

打 tag 的操作簡單到幾乎不值得單獨說明：

git tag v1.0-final

一行命令，一秒完成。如果想給過去的某個提交補打標籤，加上提交編號就行：

git tag v0.5-first-review 6fc0a77

什麼時候該打 tag？不需要每次提交都打——那就失去了"標記重點"的意義。對於我這個兩週半的項目，大概這些時刻值得標記：

30 次提交，5 到 8 個 tag，足夠覆蓋所有關鍵節點。每個 tag 就像在一本 30 頁的書裏貼了幾個書籤——你不需要逐頁翻找，直接翻到書籤那頁就行。

在 vibe coding 的場景下，tag 還有一個額外的好處：當你在一個新的 AI 對話中說"幫我對比一下從上次評審到現在改了什麼"，AI 可以直接執行 git diff v0.5-first-review..HEAD，精確拿到所有差異。不需要你記住哪個提交編號對應哪個版本，tag 名字本身就是最好的索引。

這篇文章講的四件事——.gitignore、不用文件名管版本、寫好提交說明、給關鍵節點打 tag——沒有一件是什麼高深技術。它們是 Git 使用者的基本功，是任何工程背景的人都會自然習得的常識。但我不是工程師，Git 對我來說是"聽說應該用"的工具，不是"知道怎麼用好"的工具。我知道 git add 和 git commit，夠用了——至少我以為夠用了，直到 2.7 GB 的倉庫告訴我，光會提交不代表會管理。

這些隱性知識不是 AI 會主動教你的。你說"幫我提交"，AI 執行 git commit，但不會說"你是不是忘了寫 .gitignore"。你說"幫我保存這個版本"，AI 幫你複製文件加 -v2 後綴，但不會說"你不該這麼做"。AI 回應你的指令，但不會糾正你的習慣。

給讀者的行動清單

1. 1. 新項目的第一個文件是 .gitignore。在 git init 之後、寫任何代碼之前，先讓 AI 根據你的技術棧生成一個。Python 項目、Node.js 項目、數據分析項目，AI 都能給出覆蓋全面的模板。這件事只需要做一次，但能避免倉庫從第一天開始就積累垃圾。
2. 2. 永遠不要用文件名後綴管理版本。如果你發現自己在創建 -v1、-v2、-v3，這恰好說明你需要的是 Git branch 或 tag，而不是文件拷貝。一個文件，一個名字，所有歷史交給 Git。
3. 3. 讓 AI 幫你寫提交說明。每次準備提交之前，對 AI 說"幫我看看這次改了什麼，寫一個提交說明"。它會根據代碼差異生成一條具體、清晰的信息，比你自己想的更快，比 "refine" 有用得多。