A.1 數位資產管理的本質與 Antigravity 作戰視圖:從「檔名地獄」到「一鍵版本受控」
學完本節,你能夠:
- 說明「複製檔案改檔名」這種備份方式會造成哪三種營運風險。
- 畫出 Git 的四個區域(工作目錄、暫存區、本地版本庫、遠端版本庫),並說出檔案在其中如何移動。
- 讀懂
git status的輸出,判斷一個專案資料夾目前有哪些變更還沒存進版本庫。
壹、開場情境:五個「最終版」
📌 以下為教學情境(依實務改編)。
第 1.1 節的外貿公司,報價表由台北業務、德國業務和財務三個人輪流維護。三個月後,共用雲端硬碟裡出現了這些檔案:
報價單_最終版.xlsx
報價單_最終版_財務修訂.xlsx
報價單_真最終版_v3.xlsx
報價單_最終版(1).xlsx
報價單_最終版_Kevin改.xlsx
主管問了三個問題,沒有人答得出來:
| 主管的問題 | 為什麼答不出來 |
|---|---|
| 「現在該用哪一份報價?」 | 五個檔案都叫最終版,修改時間也被同步軟體改亂了 |
| 「A 款從 €100 改成 €112,是誰改的?為什麼?」 | 檔案裡只有結果,沒有修改人、時間與理由 |
| 「德國業務的修改是不是被財務那份蓋掉了?」 | 兩人各自另存新檔,沒有人負責把兩份合起來 |
本附錄要解決的問題: 讓每一次修改都有「誰、何時、改了什麼、為什麼」的紀錄,可以隨時回到任何一個舊版本,多人同時修改時也不會互相覆蓋。這套工具叫做 Git,是全世界軟體團隊管理程式碼的標準做法;我們借用它來管理報價表、規則與程式碼。
貳、Git 的四個區域
Git 把一個專案資料夾的檔案分成四個地方存放。先記住這張圖,後面五節的所有操作都是在這四格之間搬東西。
你正在編輯的檔案"] -->|"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() 和人的工作。
本節小結
- 檔名版本管理的問題不是不夠勤勞,而是缺少「誰、何時、改了什麼、為什麼」的紀錄機制。
- Git 的四個區域:工作目錄 →
git add→ 暫存區 →git commit→ 本地版本庫 →git push→ 遠端版本庫。 - Git 最適合文字檔(CSV、Markdown、程式碼);Excel、Word 只能存版本,不能逐行比對與合併。
- 在 Antigravity 裡可以用自然語言請代理操作 Git,但要能用
git status核對結果。
柒、練習
- 讀狀態(5 分鐘):如果
git status顯示Your branch is ahead of 'origin/main' by 2 commits.,代表四個區域中哪兩格不一致?下一步該下什麼指令? - 整理資料夾(20 分鐘):列出你目前某個課堂報告資料夾裡的所有檔案,把它們分成「應該進版本庫」「不該進版本庫」「是二進位檔、應考慮另存一份文字版」三類,並說明理由。
- 管理反思(討論):如果公司規定「所有報價只能改
quotes.csv,而且每次 commit 都要寫理由」,業務會覺得比較麻煩。請從稽核成本、出錯後的追查時間、新人交接三個角度,討論這個規定值不值得。