A.6 變更時光機與審計軌跡:PR 審批與歷史究責(git blame)

學完本節,你能夠:

  1. 用 git blame、git log -S、git show 查出某一行是誰、何時、以什麼理由改的,並說出這些紀錄的可信度限制。
  2. 用 git revert 以「新增一筆反向修改」的方式撤銷錯誤,而不是改寫歷史。
  3. 設計一個 Pull Request 審核流程,讓關鍵規則的修改必須經過第二個人核准(四眼原則)。

壹、開場情境:底線被改成 5%

📌 以下為教學情境(依實務改編)。

季度檢討時,財務發現 9 月有一批 300 把 A 款鍵盤以 €95 成交,毛利率只有 6.4%,遠低於 15% 底線。奇怪的是,業務說報價前有按「檢查報價毛利」,系統顯示 ✅ 放行。

第 1.1 節最後列過一個限制:任何人都能修改 MIN_MARGIN。打開 Code.gs,第 2 行果然是:

const MIN_MARGIN = 0.05;    // 毛利底線:低於此值必須重新報價

若這批訂單以 A.4 決定的 €110 報價,每把可多收 €15,300 把合計 €4,500(以匯率 31.5 計約 NT$ 141,750)。

本節要解決的兩個問題:

  1. 事後追查:這一行是誰、什麼時候、為什麼改的?
  2. 事前預防:以後關鍵規則的修改,能不能一定要有人核准才生效?

貳、兩種工具:事後追查與事前審核

事後追查 事前審核
工具 git blame、git log -S、git show GitHub Pull Request + 分支保護規則
回答的問題 誰在何時以什麼說明改了這一行? 這個修改有沒有經過另一個人核准?
內控概念 稽核軌跡(audit trail) 四眼原則(four-eyes principle)、職能分工
限制 只能告訴你「發生了什麼」,無法阻止 需要事先設定,且審核者要真的看

參、事後追查:這一行是誰改的?

1. git blame:每一行最後是誰改的

對代理說:「查出 Code.gs 第 2 行是誰、什麼時候改的,以及那次 commit 的說明。」

git blame -L 2,2 Code.gs
3319e931 (Kevin Lin 2026-09-12 16:42:10 +0800 2) const MIN_MARGIN = 0.05;    // 毛利底線:低於此值必須重新報價
欄位 內容
3319e931 最後修改這一行的 commit 編號
Kevin Lin 該 commit 的作者
2026-09-12 16:42:10 +0800 修改時間(台灣時區)
2 行號

2. 看那次修改的完整內容與理由

git show 3319e931
commit 3319e931803ff1cfa29a4ccc1b15aba3f6f811c4
Author: Kevin Lin <kevin@example.com>
Date:   Sat Sep 12 16:42:10 2026 +0800

    chore: 展覽期間暫時放寬底線

diff --git a/Code.gs b/Code.gs
...
-const MIN_MARGIN = 0.15;    // 毛利底線:低於此值必須重新報價
+const MIN_MARGIN = 0.05;    // 毛利底線:低於此值必須重新報價

說明寫著「展覽期間暫時放寬」,但展覽結束後沒有人改回來,也看不出有誰同意過。

3. 找出某個數值是哪一次出現的

git blame 只看得到最後一次修改。如果之後又有人動過這一行,要找「0.05 是什麼時候出現的」,改用 -S 搜尋:

git log --oneline -S "MIN_MARGIN = 0.05" -- Code.gs
3319e93 chore: 展覽期間暫時放寬底線

4. 這些紀錄可以全信嗎?

紀錄 可信度 原因
commit 的作者姓名、email ⚠️ 中 由各人電腦上的 git config 自行設定,可以填別人的名字
commit 的時間 ⚠️ 中 取自當事人電腦的時鐘,也可以被修改
GitHub 上的推送與合併紀錄、PR 核准紀錄 ✅ 較高 綁定登入的 GitHub 帳號,由平台記錄
commit 說明 ⚠️ 只代表當事人的說法 「主管同意了」寫在說明裡,不等於主管真的同意

所以 git blame 是追查的起點,不是定罪的證據。要讓紀錄有證據力,需要平台端的審核紀錄,也就是下一段的 Pull Request。(進階做法是要求 commit 數位簽章,本書不展開。)

5. 撤銷錯誤:git revert

對代理說:「撤銷 3319e931 這次修改,用新增一筆 commit 的方式,不要改寫歷史。」

git revert --no-edit 3319e931
[main 98c3202] Revert "chore: 展覽期間暫時放寬底線"
 1 file changed, 1 insertion(+), 1 deletion(-)

MIN_MARGIN 回到 0.15,而原本那筆錯誤的 commit 仍留在歷史裡,稽核時看得到「改錯了、何時改回來」。

⚠️ 不要用改寫歷史的方式「湮滅」錯誤

git reset --hard 搭配 git push --force 可以讓那筆 commit 從 main 上消失,但這會破壞稽核軌跡,也會影響已經下載過的同事。已推送的錯誤,一律用 git revert。


肆、事前審核:Pull Request 與分支保護

1. Pull Request 是什麼

Pull Request(PR) 是 GitHub 上的「合併申請」:你在分支上做好修改並推送後,申請把它合併進 main。審核者可以在網頁上看到修改前後的對比、逐行留言、要求修改或核准。

sequenceDiagram actor K as 業務 Kevin participant G as GitHub actor F as 財務主管 K->>G: 推送分支 rule/expo-margin 並開 PR G-->>F: 通知:有 PR 等待審核 F->>G: 查看修改:MIN_MARGIN 0.15 → 0.05 F->>G: 留言要求:註明期限與適用產品 K->>G: 補充說明並更新修改 F->>G: 核准(Approve) K->>G: 合併到 main

2. 把規則寫下來:誰可以改 main?

主管說的話 需要追問的問題 寫成規格(GitHub 設定)
「改規則要經過我」 怎麼確保沒有人跳過? 對 main 設定分支保護:必須透過 PR 才能合併
「要有人看過」 幾個人?誰? 至少 1 位核准;Code.gs 指定財務主管為審核者
「不能自己批自己」 開 PR 的人能核准自己嗎? GitHub 本身不允許 PR 作者核准自己的 PR
「核准後又偷改呢?」 核准後再推送新修改怎麼辦? 開啟「有新 commit 時撤銷先前的核准」

這些設定位於 GitHub 版本庫的 Settings 中的分支保護規則(Branches / Rules)。其中「Code.gs 指定財務主管為審核者」需要在版本庫加入 CODEOWNERS 檔案(例如 Code.gs @財務主管帳號),並在分支規則中開啟「Require review from Code Owners」才會強制生效。

💡 GitHub 免費方案的私人版本庫,可能無法使用分支保護功能;學生可申請 GitHub Education 取得進階方案。實際可用功能以 GitHub 當時的方案說明為準。

3. 動手:開一個 PR

對代理說:「開一個 rule/expo-margin 分支,把 MIN_MARGIN 改成 0.10,commit 後推送,並向 main 開一個 Pull Request,標題『展覽期間毛利底線調整申請』,內文寫明理由、期限與影響產品。」

git switch -c rule/expo-margin
# 修改 Code.gs 後
git commit -am "chore(rule): 展覽期間毛利底線暫調為 10%"
git push -u origin rule/expo-margin

# 若電腦上有 gh 工具,可直接開 PR;否則到 GitHub 網頁按「Compare & pull request」
gh pr create --base main --title "展覽期間毛利底線調整申請" --body "理由:…;期限:…;影響產品:…"

PR 內文由你提供理由與期限。代理可以幫你補上「改了哪些檔案、哪些行」以及各產品在新底線下的毛利試算,但不要讓代理替你編寫主管同意之類的事實。

4. 審核者要看什麼

檢查項目 怎麼看
改了哪些行 PR 頁面的 Files changed(紅綠對照)
理由與期限是否清楚 PR 內文;不清楚就留言要求補充
對報價的影響 請代理或自己用新底線重跑 checkQuotes()
有沒有夾帶無關修改 檔案清單是否只有預期的檔案

伍、判斷看看

情況 該用哪個工具? 說明
想知道 C 款價格最近一次是誰改的 git blame quotes.csv 看第 4 行
想知道 A 款曾經出現過哪些價格 git log -p -- quotes.csv -p 會列出每次修改的內容
發現上週推送的報價錯了 git revert <編號> 保留歷史,新增反向修改
不希望再有人未經同意改 MIN_MARGIN PR + 分支保護 事前預防勝於事後追查
blame 顯示是「王經理」改的 再查 GitHub 上的推送帳號與 PR 紀錄 作者名稱可以自行設定

陸、回到情境與小結

git blame 在一分鐘內找出 MIN_MARGIN 是 9 月 12 日以「展覽期間暫時放寬」為由改成 0.05,git revert 把它改回 0.15,並保留了錯誤與修正兩筆紀錄。設定分支保護後,下一次調整底線必須經過財務主管在 PR 上核准,核准紀錄由 GitHub 保存。

限制 後果 在哪裡處理
審核者只按核准、沒有真的看 PR 流於形式 審核清單(第肆段第 4 點);第 12 章 團隊協作
Code.gs 在版本庫裡,但試算表上的 Apps Script 可以被直接修改 繞過 PR 直接改線上程式 第 9 章 權限隔離;第 6 章 部署流程
「暫時」的修改沒有到期提醒 展覽結束仍沒改回 在 PR 寫明期限,並建立追蹤事項

💡 最後一點很重要:Git 管的是版本庫裡的檔案。如果團隊仍可以直接在 Google 試算表的 Apps Script 編輯器裡改程式,版本庫就不是唯一的真實來源。要讓 PR 真正有效,必須規定「線上程式只能由版本庫部署更新」。

本節小結

  1. git blame 查每一行最後是誰改的;git log -S 找某個值何時出現;git show 看完整修改。
  2. Git 的作者與時間由個人電腦設定,是追查起點而非鐵證;平台端的 PR 與核准紀錄可信度較高。
  3. 已推送的錯誤用 git revert 撤銷,保留稽核軌跡;不要用強制推送改寫歷史。
  4. PR + 分支保護把「改規則要有人核准」從口頭要求變成系統強制,落實四眼原則。

附錄 A 總整理

小節 解決的問題 關鍵指令
A.1 檔名地獄,不知道哪份是現行版本 git status
A.2 修改沒有理由與紀錄 git init、git diff、git add、git commit、git log
A.3 試算會動到現行報價 git switch -c、git stash、git merge
A.4 兩人改了同一個價格 解決衝突標記、git merge --abort
A.5 歷史只在一台電腦、同事看不到 git push、git pull、git clone
A.6 關鍵規則被誰改了、如何防止 git blame、git revert、Pull Request

柒、練習

  1. 追查(5 分鐘):在你的練習版本庫中,對 quotes.csv 執行 git blame,寫出 A 款那一行最後是哪個 commit、誰、何時改的。
  2. 撤銷與送審(20 分鐘):在練習版本庫中把 TARGET_MARGIN 改成 0.25 並推送到 main,然後用 git revert 撤銷;接著改用分支 + PR 的方式重新提出這個修改,PR 內文寫明理由、期限與 A、B、C 三款的影響。
  3. 管理反思(討論):有人說「有了 git blame 就能找到犯錯的人,所以不需要 PR 審核」。請從事前預防與事後究責、可信度、組織文化三個角度回應。再想一想:如果每次追查都是為了找人究責,團隊成員會怎麼寫 commit 說明?

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

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

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

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