Git 入門：給 AI 使用者的版本控制基礎，讓代理改壞也能還原

Git 入門對 AI 使用者來說，只需要先抓住一件事：讓 AI 代理改你的檔案之前，先留一個能回得去的版本。代理一次可能改十幾個檔案，你很難憑記憶知道它動了哪裡；有了 Git，你可以逐行看到它改了什麼，不滿意就還原。這篇不談安裝步驟，只講概念、最少要會的指令，以及和 AI 代理一起工作時的使用習慣。

Git 是什麼？為什麼 AI 使用者需要它

版本控制（Version control）是一種記錄檔案隨時間變化的系統，讓你之後可以叫出某個特定版本。Pro Git 這本官方線上書指出，它讓你可以把個別檔案或整個專案還原到先前的狀態、比較不同時間的變化，而且搞砸或遺失檔案時也比較容易救回來。它不只適用程式碼，幾乎任何檔案都能用。

Git 是目前最常見的版本控制工具。GitHub 的官方文件把它歸類為分散式版本控制系統：每個人手上都有完整的專案與歷史紀錄，不需要一直連著中央伺服器。所以 Git 大部分的操作只用到你自己電腦上的檔案，沒有網路也能查歷史、比較差異、提交。

很多人用「複製一份資料夾、在名稱加上日期」來留備份。Pro Git 也提到這種做法很常見，但很容易出錯，例如忘了自己在哪個資料夾裡、不小心覆蓋到錯的檔案。

和 AI 代理一起工作時，Git 解決的是三個實際問題：

• 看得見：代理改了哪些檔案、每個檔案改了哪幾行，一個指令就能列出來。
• 回得去：改壞了，可以回到代理動手前的版本。
• 分得開：可以讓代理在另一條「分支」上實驗，不影響你原本能用的版本。

五個核心概念

名詞	一句話	和 AI 代理的關係
儲存庫（Repository）	Git 管理的專案，包含所有檔案、資料夾和每個檔案的修改歷史	代理工作的範圍，最好就是這一個資料夾
提交（Commit）	專案在某個時間點的快照，附上說明訊息	代理動手前、確認結果後各提交一次
分支（Branch）	指向某個提交、會隨新提交往前移動的指標，用來分出不同的開發路線	讓代理在分支上實驗，主線保持乾淨
差異（Diff）	兩個版本之間新增與刪除的每一行	檢查代理成果最直接的方式
.gitignore	列出「不要讓 Git 追蹤」的檔案規則	把金鑰、.env 這類機密排除在外

儲存庫：Git 管理的專案資料夾

儲存庫（Repository）是 Git 管理的專案，包含專案裡所有的檔案、資料夾，以及每個檔案的修改歷史。GitHub 的文件說明，因為 Git 是分散式的，每個儲存庫都是獨立完整的單位，有一份副本的人就能看到全部的程式碼和歷史。

在一般資料夾裡執行 git init，Git 會在裡面建立一個隱藏的子資料夾來存放版本資料；用 git clone 則是把別處已有的專案，連同完整歷史複製一份到你的電腦。

提交：專案在某一刻的快照

提交（Commit）是把專案目前的狀態存成一個快照，並寫下一句說明。Pro Git 的說法是：每次提交，Git 基本上就是替你所有的檔案在那一刻拍一張照片。

Git 裡的檔案有三種狀態，弄懂它們，git status 的輸出就看得懂了：

• 已修改（Modified）：檔案改過了，但還沒存進版本紀錄。
• 已暫存（Staged）：用 git add 標記，表示「這個版本要放進下一次提交」。
• 已提交（Committed）：已經安全地存進你電腦上的版本資料庫。

另外，Git 還沒開始管理的新檔案叫未追蹤（Untracked）。新檔案要先 git add 一次，Git 才會把它納入之後的快照。

Pro Git 特別提醒一點：提交過的內容幾乎都能找回來，但從未提交過的內容，弄丟了很可能就找不回來。這也是「先提交、再讓代理動手」的根據。

分支：不影響主線的實驗路線

分支（Branch）是指向某個提交、會隨著新的提交自動往前移動的指標。Pro Git 說明，Git 的分支非常輕量，建立一個分支只是多建立一個指標；你常看到的 main 或 master 也只是分支名稱，本身並不特別。

對 AI 使用者來說，分支的用途很單純：想讓代理試一個不確定的做法，就先開一個新分支。結果好就合併回來，不好就切回原本的分支，主線完全不受影響。

差異：逐行檢查代理改了什麼

差異（Diff）是兩個版本之間的逐行比較：哪些行被新增、哪些行被刪除。Pro Git 的說明是，git status 只告訴你哪些檔案改了，git diff 則會列出確切新增和刪除的每一行。

代理說「我已經完成了」的時候，不要只看它的總結，請自己看一次差異。這和 AI 代理任務說明怎麼寫 裡「要求代理附上證據」是同一個道理。

.gitignore：哪些檔案不該被提交

.gitignore 是一個文字檔，每一行是一條規則，列出 Git 應該忽略、不要追蹤的檔案。Pro Git 建議在新的儲存庫一開始就把它設好，以免不小心提交了根本不想放進去的檔案，例如記錄檔或自動產生的檔案。

對 AI 使用者來說，最重要的一條是排除放金鑰的檔案。很多工具會把 API 金鑰放在 .env 檔（一個用來存放環境變數設定的文字檔）裡，它就應該寫進 .gitignore：

.env

但要注意一個常見誤會：Git 的官方文件說明，.gitignore 只對還沒被追蹤的檔案有效，已經被追蹤的檔案不受影響。如果某個檔案早就被提交過，要先用 git rm --cached 檔名 讓 Git 停止追蹤它，再把它加進 .gitignore。而它在舊提交裡的內容仍然存在，這就是下一節要講的狀況。

最少要會的指令

下面這組指令，足以應付「讓代理工作、檢查、存檔或還原」的日常流程。指令要在終端機裡、專案資料夾內執行；終端機還不熟，請先看 終端機基礎。

指令	用途
git init	把目前的資料夾變成 Git 儲存庫
git clone 網址	把現有的專案連同完整歷史複製到你的電腦
git status	列出哪些檔案已修改、已暫存或未追蹤
git diff	逐行列出還沒暫存的修改
git diff --staged	逐行列出已暫存、準備提交的修改
git add 檔名	把檔案目前的版本放進下一次提交（git add . 是整個資料夾）
git commit -m "說明"	把已暫存的內容存成一個快照
git log --oneline	一行一個，列出提交歷史
git switch -c 分支名稱	建立新分支並切換過去
git switch 分支名稱	切換到已有的分支
git restore 檔名	把檔案還原成上次暫存或提交的版本（會丟掉本機修改）

關於最後一個指令，Pro Git 的警告值得照抄下來：git restore 檔名 是危險的指令，你在那個檔案上所有沒提交的修改都會消失，Git 只是直接用上次的版本把它蓋過去。除非你非常確定不要那些修改，否則不要用。

和 AI 代理一起工作的五個習慣

以下是本站整理的工作習慣，不是官方標準；每一項背後的依據都寫在說明裡。

1. 動手前先確認狀態乾淨：執行 git status，有沒提交的修改就先提交。這樣代理做的每一處變更，都和你自己的修改分得開，要還原時也只會還原代理的部分。
2. 不確定的任務開分支：用 git switch -c 分支名稱 開一條新路線再讓代理工作，主線維持在能用的狀態。
3. 結束後自己看差異：先 git status 看動到哪些檔案，再用 git diff 逐行檢查。特別留意你沒要求它改的檔案。
4. 滿意才提交：檢查過才 git add、git commit，提交訊息寫清楚這次改了什麼，之後才找得到。
5. 不要的部分再還原：已追蹤的檔案可以用 git restore 檔名 還原；代理新建立的檔案屬於未追蹤，git status 會列出來，確認後自行刪除。

代理工具的「復原」不能取代 Git

很多 AI 代理工具有自己的復原功能，但涵蓋範圍有限。以 Claude Code 為例，官方文件說明它的檢查點（Checkpoint，代理在修改檔案前自動儲存的快照）只追蹤它自己檔案編輯工具所做的修改：

• 只被終端機指令改動過的檔案，不在追蹤範圍內，官方建議用 Git 這類版本控制來還原。
• 你自己在工具外手動改的檔案，通常也不會被記錄。
• 資料庫、API、部署這類影響遠端系統的動作，無法用檢查點還原。

文件也明確表示，檢查點是給單一工作階段快速復原用的，長期的版本歷史和協作，仍要靠 Git。遠端動作的風險，要靠權限設定和人工確認來控制，詳見 讓 AI 代理安全操作電腦。

不小心把金鑰提交了怎麼辦？

先講結論：第一步是讓金鑰失效，不是去改歷史紀錄。

GitHub 的官方文件說明，如果你要移除的機密資料是密碼、Token 或憑證，第一步就是撤銷或輪替它；一旦失效，別人拿到也不能用，這樣可能就已經足夠。真的要從歷史紀錄中刪除，需要改寫歷史，會讓提交的識別碼全部改變、需要所有協作者配合清理，而且已經被別人複製或分叉的副本，你無法替他們清除。

所以實務上的順序是：

1. 到服務商的後台撤銷那把金鑰，建立新的。
2. 檢查有沒有異常用量。
3. 把新金鑰改放在 .env 這類不會提交的地方，並確認 .gitignore 已經排除它。
4. 是否還要改寫歷史，再依專案是否公開、有多少人複製過來判斷。

金鑰的保管原則，請看 API Key 是什麼，以及怎麼安全保管。

Git 和 GitHub 的差別

	Git	GitHub
是什麼	記錄版本的工具	存放 Git 儲存庫的線上服務
在哪裡運作	你的電腦，不需要網路	網路上的伺服器
主要功能	提交、分支、比較差異、還原	存放儲存庫、議題討論、合併請求、程式碼審查等協作功能
一定要用嗎	想留版本就需要	只替自己的專案留版本時，不一定需要

GitHub 的官方文件說明，GitHub 是用來存放 Git 儲存庫、並在上面提供協作工具的平台。換句話說，Git 是底層的工具，GitHub 是建立在它之上的服務；你可以只用 Git，不用 GitHub。

接著看什麼

• 還不熟悉終端機：終端機基礎
• 讓代理工作前，先把範圍與權限設好：讓 AI 代理安全操作電腦
• 把任務交代清楚，並要求代理附上證據：AI 代理任務說明怎麼寫
• 金鑰保管：API Key 是什麼，以及怎麼安全保管
• 名詞不熟：到 名詞小辭典 查，例如 Git、儲存庫、提交、分支、.gitignore。