A.2 無痛版本流轉:初始化、變更檢視、暫存與結構化提交

學完本節,你能夠:

  1. 建立一個 Git 版本庫,並用 .gitignore 排除不該存檔的檔案。
  2. 用 git diff 檢查修改內容,用 git add 挑選這次要存檔的檔案。
  3. 寫出一則讓半年後的稽核人員看得懂的 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

貳、一次存檔的生命週期

flowchart LR A["編輯 quotes.csv"] --> B["git diff
確認改了什麼"] 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 搭配平台帳號與審核紀錄

本節小結

  1. 存檔流程:git diff 檢查 → git add 挑選 → git commit 寫理由 → git log 查詢。
  2. .gitignore 決定哪些檔案 Git 看不見;個人筆記與暫存檔應該列進去。
  3. commit 說明的標題寫「做了什麼」、內文寫「為什麼」;一次 commit 只做一件事。
  4. 代理可以幫你起草說明,但「為什麼」只有你知道。

柒、練習

  1. 改數字(5 分鐘):把 C 款報價從 200 改成 190。執行 git diff,寫出你預期看到的 - 與 + 兩行,並寫一則合格的 commit 說明(C 款 €190 在匯率 31.5 下毛利率為 19.8%)。
  2. 拆 commit(20 分鐘):同時修改 quotes.csv(B 款改 160)與新增 terms.md(報價有效期限 30 天),然後用兩次 git add + git commit 分開存檔。最後用 git log --oneline 確認出現兩筆紀錄。
  3. 管理反思(討論):如果讓 AI 代理全自動寫 commit 說明、不經人看過,半年後的歷史紀錄會有什麼問題?公司應該規定哪些資訊一定要由人填寫?

國立臺中科技大學 國際貿易系 / 企業管理系 專用教材

《現代軟體工程:商學院的 AI 系統思維與 Agent 實踐》

作者:陳俊智 博士 Dr. Chun-Chih Chen

本書章節架構改編自陳鍾誠教授(金門大學)開源課程《現代軟體工程》(github.com/ccc115a/se,MIT 授權),內容針對商學院全面改寫與擴充。