用 AI 寫程式前該懂的 Git：分支、提交與還原

讓 AI 代理改程式最常出事的不是它寫錯，而是它寫錯了你回不去。解法不是先學整套 Git，而是先學會做檢查點：隨時能回到「還沒讓它動手之前」。

這篇只挑「還原得回來」用得到的那一小套，依 Git 與 GitHub 官方文件。讀完你會裝好 Git、做出第一個提交、開分支再放手，也分得清 restore、reset、revert 哪一個會把沒存的修改丟掉。

讓代理動手之前，先有一個回得去的點

人改程式一次改一處，出錯了還記得動過哪裡。代理不是這樣：一個回合它可能讀十幾個檔案、改其中五個，還動到你沒注意的設定，修改散在好幾個檔案裡，復原鍵幫不上忙。

提交（commit）是你自己蓋的存檔點，分支（branch）是一條可以整條丟掉的支線。把這兩件事放進流程，讓代理改程式就變成一個固定循環。

1. 開一條分支，主線先保持乾淨
2. 動手之前先提交一個檢查點
3. 把目標與完成條件講清楚，讓代理去改
4. 用 git diff 把改過的每一行看過
5. 跑專案自己的測試
6. 過了就合併回主線，沒過就整條丟掉

給程式代理的提示模式：先規劃、再實作、最後驗證

閱讀完整文字說明

一張六步驟的流程圖。上排由左到右是三步：1 開一條分支，指令 git switch -c ai/login，main 先保持乾淨；2 先做一個檢查點，指令 git add -A 與 git commit，這是代理動手前的存檔點；3 讓代理改，把目標與完成條件講清楚，改幾個檔都在這條分支上，這一格是代理在做的事，用藍色標示。接著往下轉到中排，由右到左是三步：4 看它改了什麼，用 git diff 與 git log，一行一行看過再往下；5 跑測試，跑專案自己的測試，沒過就回到步驟 3，圖上用一條虛線箭頭畫出這個回頭的路徑；6 收尾，合併或丟掉二選一，不要留著半成品分支。最後從第六步分成兩條路：測試過了就合併回 main，指令是 git switch main 接 git merge ai/login，再用 git branch -d 刪掉分支；不要了就整條丟掉，指令是 git switch main 接 git branch -D ai/login，main 沒被動過，等於沒發生。

安裝 Git 與第一次設定

macOS 用 Homebrew 或 Xcode 命令列工具，Debian 與 Ubuntu 用 apt，Windows 到 Git 官網下載頁抓安裝程式。裝完用 git --version 確認，查證當天官網列出的最新版本是 2.55.0。

# macOS：Homebrew，或改用 Xcode 命令列工具
brew install git
xcode-select --install

# Debian / Ubuntu（官網列的是 apt-get install git）
sudo apt-get install git

# Windows：到 Git 官網的 Windows 下載頁取得安裝程式

# 裝好了沒
git --version

接著設定身分，每個提交都會記下作者是誰。--global 對這台電腦所有儲存庫生效，做一次就好，專案 .git 目錄裡那份設定比全域優先。順便把預設分支設成 main：官方文件說明 git init 的預設分支名稱仍是 master，Git 3.0 才換成 main。

git config --global user.name "你的名字"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

# 看目前的設定，以及每一條是從哪個檔案來的
git config --list --show-origin

Claude Code｜終端機、路徑與 Git 基礎

最小循環：init、status、add、commit

git init 會在專案資料夾建立一個空的儲存庫，也就是一個 .git 目錄，加 -b 可指定初始分支名稱。之後的日常只有四個動作：改檔案、git status 看狀態、git add 放進索引、git commit 收成提交。

cd my-project
git init -b main

git status            # 哪些改了、哪些已進暫存區、哪些還沒被追蹤
git add README.md     # 指定單一檔案
git add -A            # 這次的全部變更
git commit -m "第一個提交"

git add 的目的地叫索引（index），官方文件也稱它為暫存區（staging area），用來準備下一個提交要放什麼，commit 只收錄索引裡的東西。git commit -a 可省掉 add，但官方寫明它只自動暫存已修改與已刪除的檔案，新檔案不受影響——代理新增的檔案常常就這樣漏掉。

看它改了什麼：git diff 與 git log

代理說「改好了」不等於改對了。git diff 不加參數看的是工作目錄相對於索引，也就是還沒 add 的部分；--staged 看索引相對於上一個提交，也就是現在 commit 會提交什麼；HEAD 是兩邊加起來。git log 則是看歷史，官方文件說明 --graph 會在左邊畫出分支與合併的文字圖。

git diff              # 還沒暫存的修改
git diff --staged     # 已暫存、下一個提交會帶走的修改
git diff HEAD         # 相對於上一個提交的全部改動
git diff --stat       # 只看哪些檔案各動了幾行

git log --oneline --graph    # 一行一個提交，左邊附分支圖
git log -p README.md         # 這個檔案每次改了什麼

Claude Code｜Git、差異審查與 PR

AI 寫的程式能信嗎：審查、測試與安全檢查清單

開一條分支，改壞了就整條丟掉

git switch -c 會建立一條新分支並切過去，官方文件說它等同於先 git branch 再 git switch。代理在這條分支上做什麼都影響不到主線，要丟也是丟一整條。

git switch -c ai/login        # 開一條新分支並切過去
# ……讓代理改，看 diff，跑測試……

git switch main               # 回主線
git merge ai/login            # 滿意：合併進來
git branch -d ai/login        # 已經合併過，安全刪除

git branch -D ai/login        # 不要了：強制刪除，沒合併也刪

開分支後主線沒有新提交的話，合併只是把主線的指標移過去，官方稱為快轉合併（fast-forward）。衝突時可用 git merge --abort 回到合併前，但官方提醒：開始時若還有未提交的修改，不一定救得回來。

刪分支有兩級：git branch -d 要求已完全合併才肯刪，git branch -D 是 --delete --force 的簡寫，沒合併也照刪。試錯分支確定不要才用 -D。

Claude Code｜Git Worktree 平行工作

三種「還原」差在哪裡

• git restore 換的是檔案內容：預設用索引的版本覆蓋工作目錄，把還沒 add 的修改丟掉；加 --staged 則用 HEAD 覆蓋索引，把已 add 的退出暫存區。
• git reset 動的是分支指向哪個提交：--soft 只移動 HEAD，預設的 --mixed 連索引一起更新、工作目錄保留，--hard 則連工作目錄一起覆蓋。
• git revert 不改寫歷史，而是照舊提交做一個反向的新提交；官方原話是把那些提交帶來的修改反轉過來並記錄成新的提交，它要求工作目錄是乾淨的。

git restore src/app.js          # 丟掉這個檔案還沒暫存的修改
git restore --staged src/app.js # 退出暫存區，內容留著

git reset --soft HEAD~1         # 取消上一個提交，修改全留著
git reset HEAD~1                # 同上，但暫存區也清掉（預設 --mixed）
git reset --hard HEAD~1         # 連工作目錄一起回去，修改直接消失

git revert 1a2b3c4              # 新增一個反向提交，歷史留著

判準很簡單：還沒提交用 restore，提交了但還沒推出去用 reset，已經推上遠端別人可能拉走了，就只能用 revert。這個分工在官方文件的 revert 說明裡也寫得很清楚。

.gitignore：密鑰與相依目錄不該進儲存庫

.env 與各種金鑰檔、node_modules 這類可重裝的相依目錄、建置產物，都不該進儲存庫。做法是在專案根目錄放一個 .gitignore，官方定義是：指定「刻意不追蹤、Git 應該忽略」的檔案。代理很常 git add -A，這份清單要先寫好。

# 密鑰與環境變數
.env
.env.*
*.pem
*.key

# 可以重新產生的東西
node_modules/
dist/
build/
__pycache__/

# 系統與編輯器
.DS_Store
.idea/

最常踩的坑是：.gitignore 只管還沒被追蹤的檔案，官方明講「已經被 Git 追蹤的檔案不受影響」。已經進過提交的檔案，要先用 git rm --cached 從索引移除，再寫進 .gitignore。

git rm --cached .env       # 從索引移除，檔案留在硬碟上
echo ".env" >> .gitignore
git commit -m "stop tracking .env"

推到 GitHub：remote、push 與憑證

先在 GitHub 建一個空的儲存庫，再把它設成本機的遠端。GitHub 官方文件提醒：建立時不要勾選 README、授權條款或 .gitignore，這些等推上去之後再加。

git remote add origin 你的儲存庫網址
git remote -v                  # 確認網址對不對
git push -u origin main        # 第一次推，順便記住上游分支

網址有 HTTPS 與 SSH 兩種，GitHub 官方文件沒有偏好，只說明差別：HTTPS 網址所有儲存庫都有，在防火牆或 Proxy 後面也能用，但要搭配憑證輔助工具；SSH 要先產生金鑰加到帳號。另外 GitHub 已移除 Git 的密碼驗證，走 HTTPS 時填的是個人存取權杖。

# GitHub 建議的演算法
ssh-keygen -t ed25519 -C "you@example.com"

# 舊系統不支援 ed25519 時的替代方案
ssh-keygen -t rsa -b 4096 -C "you@example.com"

代理自己的 checkpoint 不能取代 Git

多數程式代理都有自己的還原功能。以 Claude Code 為例，官方文件說明它會在你送出每一個開啟新回合的提示詞之前自動建立檢查點，用 /rewind 叫出選單，可選擇只還原程式碼、只還原對話或兩者。

但範圍有明確邊界，官方文件都列出來了：bash 指令改掉的檔案不會被追蹤；子代理做的修改通常不在這個 session 的檢查點裡，官方直接寫那種情況要用 Git 還原；在 Claude Code 之外手動改的也不算。一個 session 只留最近 100 個檢查點的快照，預設在最後一次存檔約 30 天後清掉。

官方文件那一節的標題就叫「不是版本控制的替代品」：檢查點是為了 session 層級的快速復原，長期歷史與協作還是要用 Git。分界線很好記——那個狀態你想留到明天，就 commit。

Claude Code｜Checkpoint 與 /rewind

Codex CLI 入門：在終端機裡讓 OpenAI 幫你改程式

• 教學
• 軟體與 App
• AI 寫程式與本機模型