A.1 數位資產管理的本質與 Antigravity 作戰視圖:從「檔名地獄」到「一鍵版本受控」

學完本節,你能夠:

  1. 說明「複製檔案改檔名」這種備份方式會造成哪三種營運風險。
  2. 畫出 Git 的四個區域(工作目錄、暫存區、本地版本庫、遠端版本庫),並說出檔案在其中如何移動。
  3. 讀懂 git status 的輸出,判斷一個專案資料夾目前有哪些變更還沒存進版本庫。

壹、開場情境:五個「最終版」

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

第 1.1 節的外貿公司,報價表由台北業務、德國業務和財務三個人輪流維護。三個月後,共用雲端硬碟裡出現了這些檔案:

報價單_最終版.xlsx
報價單_最終版_財務修訂.xlsx
報價單_真最終版_v3.xlsx
報價單_最終版(1).xlsx
報價單_最終版_Kevin改.xlsx

主管問了三個問題,沒有人答得出來:

主管的問題 為什麼答不出來
「現在該用哪一份報價?」 五個檔案都叫最終版,修改時間也被同步軟體改亂了
「A 款從 €100 改成 €112,是誰改的?為什麼?」 檔案裡只有結果,沒有修改人、時間與理由
「德國業務的修改是不是被財務那份蓋掉了?」 兩人各自另存新檔,沒有人負責把兩份合起來

本附錄要解決的問題: 讓每一次修改都有「誰、何時、改了什麼、為什麼」的紀錄,可以隨時回到任何一個舊版本,多人同時修改時也不會互相覆蓋。這套工具叫做 Git,是全世界軟體團隊管理程式碼的標準做法;我們借用它來管理報價表、規則與程式碼。


貳、Git 的四個區域

Git 把一個專案資料夾的檔案分成四個地方存放。先記住這張圖,後面五節的所有操作都是在這四格之間搬東西。

flowchart LR W["① 工作目錄
你正在編輯的檔案"] -->|"git add"| S["② 暫存區
挑好準備存檔的變更"] S -->|"git commit"| L["③ 本地版本庫
你電腦裡的歷史紀錄"] L -->|"git push"| R["④ 遠端版本庫
GitHub 上的共用版本"] R -->|"git pull"| W
區域 白話比喻 在這裡的東西 對應指令
① 工作目錄 你的辦公桌 正在改、還沒確認的檔案,隨時可以丟掉重來 (直接編輯檔案)
② 暫存區 待送出的公文夾 從桌上挑出來、這次要一起存檔的變更 git add
③ 本地版本庫 你自己的檔案櫃 每一次存檔(commit)的完整快照,附作者、時間、說明 git commit
④ 遠端版本庫 公司共用的總檔案室 團隊共享的版本,通常放在 GitHub git push / git pull

幾個名詞先講清楚:

  • commit(提交):一次正式存檔。Git 會替整個專案拍一張快照,並給它一組由內容算出的編號(雜湊值,例如 89dcec1)。內容只要改一個字,編號就會不同,所以舊紀錄被偷偷竄改是看得出來的。
  • 為什麼要有暫存區? 因為你常常一次改了好幾個檔案,但它們分屬不同的事。暫存區讓你把「調整 A 款報價」和「修改合約條款」分成兩次存檔,各自寫清楚理由。

⚠️ Git 最適合管理「文字檔」

Git 能逐行比對 .csv、.md(Markdown)、.gs/.js(程式碼)這類文字檔,告訴你「第 2 行從 100 改成 112」。 .xlsx、.docx 是壓縮過的二進位檔,Git 仍然能保存每個版本,但看不出改了哪一格,兩人同時修改時也無法自動合併。 所以本附錄把報價資料存成 quotes.csv,把第 1.1 節的 GAS 程式碼存成 Code.gs,一起放進版本庫。


參、在 Antigravity 裡用 Git:兩條路,同一套指令

Google Antigravity 是以代理(Agent)為核心的程式開發環境。在裡面使用 Git 有兩種方式:

  • 對代理下指令:用中文描述你要做什麼,代理會在終端機執行對應的 git 指令;依你的設定,執行前可能會先請你核准。
  • 自己下指令:在內建終端機直接輸入 git 指令。

💡 本附錄的寫法

Antigravity 的介面會隨版本更新改變,按鈕名稱與位置不一定和你看到的相同。因此每個動作我們都同時寫出「可以對代理說的話」和「實際執行的 git 指令」。以 git 指令為準:代理做了什麼,你都應該能在終端機或版本紀錄裡核對出來。不論介面怎麼變,底下跑的都是同一套 Git。

下表是整個附錄會用到的動作:

業務情境 可以對代理說 git 指令 小節
查看目前狀態 「現在有哪些檔案被改過、還沒存檔?」 git status A.1
建立版本庫 「把這個資料夾設成 Git 版本庫」 git init A.2
檢查改了什麼 「列出報價表改了哪幾行」 git diff A.2
挑選要存檔的檔案 「只把報價表加入暫存區」 git add <檔名> A.2
存檔並寫理由 「存檔,說明是依 1.1 規則重報 A 款」 git commit -m "..." A.2
查歷史 「列出所有存檔紀錄」 git log --oneline A.2
開沙盒試算 「開一個 promo/black-friday 分支」 git switch -c <分支> A.3
收起半成品 「先把沒改完的東西收起來」 git stash A.3
合併 「把促銷分支合併回 main」 git merge <分支> A.3
處理衝突 「合併衝突了,列出雙方的版本」 編輯衝突標記後 git add、git commit A.4
上傳/下載 「推送到 GitHub」「抓同事的更新」 git push / git pull A.5
送審 「替這個分支開 Pull Request」 GitHub 的 Pull Request A.6
追查是誰改的 「Code.gs 第 2 行是誰改的?」 git blame A.6

肆、動手:判斷一個資料夾的狀態

你接手了同事的 global-trade-ops 資料夾,想知道它有沒有版本控制、有沒有人改到一半。

對代理說:「這個資料夾有用 Git 管理嗎?目前有哪些檔案被修改、還沒存檔?」

代理會執行:

git status

實際輸出(範例):

On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   quotes.csv

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    notes_temp.txt

no changes added to commit (use "git add" and/or "git commit -a")

逐行翻譯:

輸出 意思 位在四個區域的哪裡
On branch main 目前在 main 這條主線上(分支在 A.3 說明) —
up to date with 'origin/main' 和 GitHub 上的版本一致,沒有未上傳的存檔 ③ 與 ④ 同步
modified: quotes.csv 報價表被改過,但還沒加入暫存區 ① 工作目錄
Untracked files: notes_temp.txt 一個 Git 從來沒記錄過的新檔案 ① 工作目錄(未追蹤)

如果資料夾根本沒有版本控制,git status 會回報 fatal: not a git repository。


伍、判斷看看:常見誤解

說法 對嗎? 說明
「我存檔(Ctrl+S)了,Git 就有紀錄了。」 ❌ Ctrl+S 只改了工作目錄,要 git add + git commit 才進版本庫
「commit 之後,同事就看得到了。」 ❌ commit 只存在你的電腦,要 git push 才會上傳到遠端
「把 .xlsx 放進 Git,就能看出改了哪一格。」 ❌ 二進位檔只能保存版本,無法逐格比對與自動合併
「用了 Antigravity 就不用懂 Git。」 ❌ 代理會幫你下指令,但核准、驗收、出事時判斷,都需要你看得懂狀態
「untracked 的檔案不會被存進版本庫。」 ✅ 除非你 git add 它;個人筆記、暫存檔最好列進 .gitignore(A.2)

陸、回到情境與小結

用 Git 管理後,主管的三個問題分別由這些機制回答:

主管的問題 Git 的對應機制 在哪一節
現在該用哪一份? 只有一份檔案,main 分支上的最新 commit 就是現行版本 A.2、A.3
誰改的、為什麼? 每個 commit 都有作者、時間與說明;git blame 可查到單一行 A.2、A.6
修改有沒有被蓋掉? 合併時同一行被兩人改到,Git 會停下來要人決定 A.4

但 Git 也有做不到的事:它只記錄「被提交的版本」,沒提交的修改不受保護;它也不會判斷報價對不對,那仍然是第 1.1 節 checkQuotes() 和人的工作。

本節小結

  1. 檔名版本管理的問題不是不夠勤勞,而是缺少「誰、何時、改了什麼、為什麼」的紀錄機制。
  2. Git 的四個區域:工作目錄 → git add → 暫存區 → git commit → 本地版本庫 → git push → 遠端版本庫。
  3. Git 最適合文字檔(CSV、Markdown、程式碼);Excel、Word 只能存版本,不能逐行比對與合併。
  4. 在 Antigravity 裡可以用自然語言請代理操作 Git,但要能用 git status 核對結果。

柒、練習

  1. 讀狀態(5 分鐘):如果 git status 顯示 Your branch is ahead of 'origin/main' by 2 commits.,代表四個區域中哪兩格不一致?下一步該下什麼指令?
  2. 整理資料夾(20 分鐘):列出你目前某個課堂報告資料夾裡的所有檔案,把它們分成「應該進版本庫」「不該進版本庫」「是二進位檔、應考慮另存一份文字版」三類,並說明理由。
  3. 管理反思(討論):如果公司規定「所有報價只能改 quotes.csv,而且每次 commit 都要寫理由」,業務會覺得比較麻煩。請從稽核成本、出錯後的追查時間、新人交接三個角度,討論這個規定值不值得。

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

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

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

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