A.2 無痛版本流轉:初始化、變更檢視、暫存與結構化提交
學完本節,你能夠:
- 建立一個 Git 版本庫,並用
.gitignore排除不該存檔的檔案。 - 用
git diff檢查修改內容,用git add挑選這次要存檔的檔案。 - 寫出一則讓半年後的稽核人員看得懂的 commit 說明,並用
git log調出歷史。
壹、開場情境:把 1.1 的報價表納入版本控制
📌 以下為教學情境(依實務改編)。
第 1.1 節的報價表跑出了紅燈:匯率跌到 31.5,A 款毛利率只剩 11.1%,系統建議重報 €112。業務改了價格,但三個月後會計師來查帳時問:「A 款為什麼從 €100 變 €112?誰決定的?」業務已經記不得了。
本節要做的,是讓這次修改留下一筆完整的紀錄。資料夾 global-trade-ops 裡有:
| 檔案 | 內容 | 要不要進版本庫 |
|---|---|---|
quotes.csv |
報價表(產品名稱、單位成本、歐元報價) | ✅ |
Code.gs |
第 1.1 節的 checkQuotes() 程式碼 |
✅ |
notes_temp.txt |
個人筆記 | 🛑 |
~$報價單.xlsx |
Excel 開檔時自動產生的暫存檔 | 🛑 |
quotes.csv 一開始的內容(匯率固定以 31.5 計):
產品名稱,單位成本TWD,歐元報價EUR
人體工學鍵盤A款,2800,100
無線雙模鍵盤B款,3900,150
靜電容旗艦鍵盤C款,4800,200
貳、一次存檔的生命週期
確認改了什麼"] B --> C["git add
挑選要存的檔案"] C --> D["git commit
寫下理由並存檔"] D --> E["git log
日後查歷史"]
其中最容易被省略、卻最重要的是 commit 的說明:檔案改了什麼,Git 會自動記錄;為什麼要改,只有人能寫。
參、把規則寫下來:什麼樣的 commit 說明才算合格?
主管說:「存檔要寫清楚。」這句話一樣需要翻譯成規格。
| 主管說的話 | 需要追問的問題 | 寫成規格 |
|---|---|---|
| 「要寫清楚」 | 寫什麼? | 標題寫做了什麼;內文寫為什麼 |
| 「看得出是哪類修改」 | 怎麼分類? | 標題開頭加類型:feat 新功能、fix 修正、docs 文件、chore 雜項 |
| 「看得出改哪一塊」 | 範圍怎麼標? | 類型後加括號註明範圍,如 fix(quote): |
| (主管沒說) | 一次存檔可以混幾件事? | 一次 commit 只做一件事;改報價與改合約要分開存 |
這種「類型(範圍): 說明」的寫法稱為 Conventional Commits,是許多開源專案採用的慣例,不是強制標準,但能讓歷史紀錄一目了然。
| 不合格的說明 | 問題 | 合格的說明 |
|---|---|---|
update |
看不出改了什麼 | fix(quote): A款依 1.1 建議重報 €112 |
111 |
沒有任何資訊 | docs(terms): 新增報價有效期限 30 天 |
改價格和合約還有修 bug |
三件事混在一起 | 拆成三個 commit |
肆、動手做
💡 每個步驟都寫出「可以對代理說的話」與「git 指令」。代理執行後,請用
git status或git log自己核對一次。
1. 第一次使用:告訴 Git 你是誰
每個 commit 都會記錄作者。第一次在電腦上使用 Git,要先設定姓名與 email(只需要做一次):
git config --global user.name "Mia Chen"
git config --global user.email "mia@example.com"
git config --global pull.rebase false # 本地與雲端都有新 commit 時用合併處理,避免出現 "fatal: Need to specify how to reconcile divergent branches"
沒設定就 commit,Git 會停下來顯示 Author identity unknown。
2. 建立版本庫與 .gitignore
對代理說:「把這個資料夾設成 Git 版本庫,並建立 .gitignore,排除暫存檔與系統檔。」
git init
# .gitignore 的內容:列在這裡的檔案,Git 會當作看不見
*.tmp
~$*
.DS_Store
Thumbs.db
notes_temp.txt
git init 會在資料夾裡建立一個隱藏的 .git 資料夾,所有歷史紀錄都存在裡面。刪掉 .git 等於刪掉全部歷史,所以不要手動動它。
⚠️ 主線叫 main 還是 master?
舊版 Git 預設的主線名稱是
master,GitHub 新建的版本庫預設是main。本附錄統一用main,可以在git init後執行git branch -M main改名,或用git init -b main直接指定。
接著把初始版本存起來:
git add quotes.csv Code.gs .gitignore
git commit -m "docs: 建立報價資料庫"
3. 修改並檢查差異
把 A 款報價從 100 改成 112,存檔後:
對代理說:「列出 quotes.csv 改了哪幾行。」
git diff quotes.csv
diff --git a/quotes.csv b/quotes.csv
index 5a41f50..b6e0bdb 100644
--- a/quotes.csv
+++ b/quotes.csv
@@ -1,4 +1,4 @@
產品名稱,單位成本TWD,歐元報價EUR
-人體工學鍵盤A款,2800,100
+人體工學鍵盤A款,2800,112
無線雙模鍵盤B款,3900,150
靜電容旗艦鍵盤C款,4800,200
讀法:- 開頭是刪掉的舊內容,+ 開頭是新內容,前面是空白的是沒變的上下文。Git 是整行比對:一行裡只改一個數字,也會顯示成「刪一行、加一行」。
💡 可以請代理順便檢查:「這次修改後,各產品的毛利率是多少?有沒有低於 15%?」代理可以依第 1.1 節的公式幫你算(A 款 €112 → 20.6%),但數字仍要你自己核對。
4. 挑選要存的檔案
對代理說:「只把 quotes.csv 加入暫存區。」
git add quotes.csv
git status --short
M quotes.csv
--short 是精簡格式:M 在第一欄表示已加入暫存區。如果你另外新增了一個沒列進 .gitignore 的檔案,它會顯示為 ?? 檔名(未追蹤);notes_temp.txt 已列進 .gitignore,所以不會出現。
5. 存檔並寫理由
對代理說:「把暫存區存檔。標題用 Conventional Commits 格式,內文說明是因為匯率下跌、A 款毛利低於底線。」
git commit -m "fix(quote): A款依 1.1 建議重報 €112" -m "匯率跌到 31.5,A款毛利率 11.1% 低於 15% 底線。"
兩個 -m:第一個是標題,第二個是內文。請代理起草說明很方便,但送出前要讀一遍:代理只看得到檔案改了什麼,看不到你們開會決定的理由,理由要由你提供。
6. 查歷史
對代理說:「列出所有存檔紀錄。」
git log --oneline
89dcec1 (HEAD -> main) fix(quote): A款依 1.1 建議重報 €112
9442cc5 docs: 建立報價資料庫
要看作者、時間與內文,把 --oneline 拿掉:
commit 89dcec13d9b9cff000d9465c856a1058af4c14e9
Author: Mia Chen <mia@example.com>
Date: Mon Sep 28 14:15:00 2026 +0800
fix(quote): A款依 1.1 建議重報 €112
匯率跌到 31.5,A款毛利率 11.1% 低於 15% 底線。
(你自己操作時,編號與時間會不同。)
伍、跑跑看、壞給你看
| 實驗 | 操作 | 預期結果 | 想想看 |
|---|---|---|---|
| ① 忘了 add | 改 quotes.csv 後直接 git commit -m "try" |
Git 拒絕,顯示 no changes added to commit |
為什麼 Git 不自動幫你把所有改過的檔案都存進去? |
| ② 反悔 | 把 B 款改成 999(還沒 add),再執行 git restore quotes.csv |
B 款回到 150 | restore 救回的是哪一個版本?沒 commit 過的修改救得回來嗎? |
| ③ 看舊版本 | git show HEAD~1:quotes.csv |
顯示 A 款仍是 100 的舊報價 | 這和翻找「報價單_最終版(1).xlsx」差在哪? |
| ④ 忽略清單 | 建一個 test.tmp,執行 git status |
test.tmp 不會出現在清單中 |
如果忘了寫 .gitignore,個人檔案會怎麼跑進公司版本庫? |
⚠️
git restore會直接丟掉工作目錄中尚未存檔的修改,而且救不回來。請代理執行這類指令前,先確認你真的不要那些修改。
陸、回到情境與小結
三個月後會計師再問「A 款為什麼漲價」,你只要執行 git log -- quotes.csv,就能列出所有動過報價表的紀錄,看到 9 月 28 日 Mia 因匯率下跌重報 €112 的說明。
| 限制 | 後果 | 在哪一節解決 |
|---|---|---|
| 所有修改都直接存進 main | 試算到一半的數字也成為「現行報價」 | A.3 分支 |
| 紀錄只在自己電腦裡 | 電腦壞了紀錄就沒了,同事也看不到 | A.5 推送到 GitHub |
| 作者姓名是自己設定的 | 任何人都能把 user.name 設成別人的名字 |
A.6 搭配平台帳號與審核紀錄 |
本節小結
- 存檔流程:
git diff檢查 →git add挑選 →git commit寫理由 →git log查詢。 .gitignore決定哪些檔案 Git 看不見;個人筆記與暫存檔應該列進去。- commit 說明的標題寫「做了什麼」、內文寫「為什麼」;一次 commit 只做一件事。
- 代理可以幫你起草說明,但「為什麼」只有你知道。
柒、練習
- 改數字(5 分鐘):把 C 款報價從 200 改成 190。執行
git diff,寫出你預期看到的-與+兩行,並寫一則合格的 commit 說明(C 款 €190 在匯率 31.5 下毛利率為 19.8%)。 - 拆 commit(20 分鐘):同時修改
quotes.csv(B 款改 160)與新增terms.md(報價有效期限 30 天),然後用兩次git add+git commit分開存檔。最後用git log --oneline確認出現兩筆紀錄。 - 管理反思(討論):如果讓 AI 代理全自動寫 commit 說明、不經人看過,半年後的歷史紀錄會有什麼問題?公司應該規定哪些資訊一定要由人填寫?