Git 與 GitHub：每一步都能回頭

你一定看過這種資料夾

報告.docx
報告_修改.docx
報告_修改_v2.docx
報告_最終版.docx
報告_最終版_真的最終版.docx

這是人類對「版本管理」最原始的嘗試。寫程式時，這種方法很快就會失控：你改了三個檔案，結果壞了，卻想不起來昨天能動的版本長什麼樣子。

Git 是專門解決這件事的工具。它像遊戲裡的存檔點：每完成一小步就存一次檔，每個存檔點都寫著「這一步做了什麼」。改壞了，隨時可以回到任何一個存檔點。

這對跟 AI 合作特別重要。Claude Code 一次可能改好幾個檔案，有了 Git，你可以清楚看到它改了哪幾行，不滿意就整個收回。有存檔點，你才敢放手讓 AI 做事。

先認識幾個詞

名詞	白話意思
repository（儲存庫）	被 Git 管理的專案資料夾，裡面的 .git 資料夾存著所有歷史
commit（提交）	一個存檔點，包含這次改了什麼和一句說明
branch（分支）	一條平行的開發路線，在上面怎麼試都不影響主線
main	主線分支的名字，放「確定可以用」的版本
GitHub	放 Git 儲存庫的網站，可以備份、分享、協作
push／pull	把存檔點推上 GitHub／從 GitHub 拉下來
Pull Request	在 GitHub 上請求「把這條分支合併進 main」，合併前可以逐行檢查

準備工作

安裝 Git。 到 Git 的官方網站（git-scm.com）下載安裝。Mac 通常已經有了，或會在第一次使用時提示你安裝。裝好後在終端機確認：

git --version

告訴 Git 你是誰。 每個 commit 都會記下作者，第一次使用時設定一次就好：

git config --global user.name "你的名字"
git config --global user.email "你的 Email"

Email 建議用之後註冊 GitHub 的同一個。

你的專案已經是儲存庫了。 還記得第 2 堂 uv init 順便做了 git init 嗎？專案裡那個 .git 資料夾就是它。如果你的專案沒有，在專案資料夾執行一次 git init 即可。

第一次存檔之前：決定什麼不能存

這一步非常重要，請不要跳過。

Git 會記住你交給它的每一個檔案，而且一旦存進歷史，就很難徹底刪除。之後推到 GitHub，它們也會跟著上去。所以有些東西絕對不能進去：

• 個人資料：expenses.csv 是你真實的花費紀錄
• 密碼和 API 金鑰：例如之後會用到的 .env 檔
• 可以重建的東西：.venv、__pycache__

打開專案裡的 .gitignore（uv 已經幫你寫好了 .venv 等幾行），在最下面加上：

# 個人記帳資料，不要放進版本紀錄
expenses.csv
expenses_backup.csv
*.xlsx

# 密碼與金鑰
.env

*.xlsx 的意思是「所有副檔名是 xlsx 的檔案」，匯出的 Excel 也包含你的資料。

存下第一個存檔點

git status

git status 是你最常用的指令，它會列出「哪些檔案是新的、哪些被改過了」。確認清單裡沒有 expenses.csv 和 .venv，再繼續：

git add .
git commit -m "建立記帳專案：模組結構、uv 環境、例外處理、型別提示與測試"

• git add .：把目前所有的修改（點代表「這個資料夾裡的全部」）放進準備區，意思是「這些要放進下一個存檔點」。
• git commit -m "..."：建立存檔點，-m 後面是這一步的說明。

在 Windows 上，你可能會看到一些關於 LF 和 CRLF 的提示，那是不同作業系統換行符號的差異，可以先不用理它。

一個檔案的修改，要經過 add 和 commit 才會變成存檔點。

每天的節奏

從今天起，每完成一小步（修好一個 bug、加好一個小功能），就跑一次這個循環：

git status              # 改了哪些檔案？
git diff                # 每個檔案改了哪幾行？
uv run pytest           # 測試都過了嗎？
git add .
git commit -m "報表加上最大的一筆花費"

git diff 會用紅色（刪掉的）和綠色（新增的）標出每一行的變化。每次 commit 前看一眼 diff，是抓到「咦，這行我沒有要改啊」最便宜的時機。

想看過去的存檔點：

git log --oneline

3f2a9c1 報表加上最大的一筆花費
a81d04e 建立記帳專案：模組結構、uv 環境、例外處理、型別提示與測試

前面那串英文數字是每個存檔點的代號。

改壞了，怎麼回頭？

狀況	指令	效果
改到一半，想放棄某個檔案的修改	git restore main.py	這個檔案回到上一個存檔點的樣子
已經 commit 了，想撤銷那一次	git revert 3f2a9c1	新增一個「反向」的存檔點，把那次的修改抵銷

git restore 會丟掉還沒 commit 的修改，用之前想清楚。git revert 則很安全，因為它不刪除歷史，只是再加一步，你隨時還能改回來。

分支：在平行世界裡試新功能

假設你想做「只看本月份」的報表，但不確定要怎麼做，可能會改得亂七八糟。這時開一條分支：

git switch -c monthly-report

-c 是「建立」的意思。現在你在 monthly-report 這條分支上，在這裡怎麼改、怎麼 commit，main 都不受影響。做壞了，切回 main（git switch main）就是原本好好的版本。

做好了、測試也都通過了，就該把它合併回 main。最好的方法是透過 GitHub。

推上 GitHub

1. 建立 GitHub 帳號（如果還沒有），然後在 GitHub 上建立一個新的 repository。

• 名稱：expense-tracker
• 選擇 Private（私人）：只有你看得到
• 不要勾選新增 README 或 .gitignore，因為你的專案裡已經有了

2. 把本機的專案連上 GitHub。 建立好之後，GitHub 頁面上會顯示一組指令，大致是這樣（網址換成你自己的）：

git remote add origin https://github.com/你的帳號/expense-tracker.git
git branch -M main
git push -u origin main

• git remote add origin ...：登記「GitHub 上的那個儲存庫」，取名叫 origin
• git branch -M main：確保主線分支叫 main
• git push -u origin main：把 main 推上去。-u 讓之後只要打 git push 就好

第一次 push 時，通常會跳出瀏覽器視窗請你登入 GitHub 授權，照畫面指示完成即可。重新整理 GitHub 頁面，你的程式碼就在上面了，而且裡面沒有 expenses.csv。

Pull Request：合併前先檢查

回到你的 monthly-report 分支，把它也推上去：

git switch monthly-report
git push -u origin monthly-report

打開 GitHub 上的專案頁面，它通常會主動提示你為剛推上來的分支建立 Pull Request（簡稱 PR）。PR 的意思是：「我想把這條分支合併進 main，請先看過。」

建立 PR 時：

• 標題寫做了什麼：「新增只看本月份的報表」
• 說明寫為什麼、怎麼測試的：「新增 filter_month 和對應的測試，uv run pytest 全部通過」

PR 頁面裡有一個列出所有修改的分頁，每一行的變化都標得清清楚楚。逐個檔案看過，確認沒問題，再按下合併。

合併之後，回到電腦上把 main 更新到最新：

git switch main
git pull
git branch -d monthly-report

最後一行刪掉本機已經用完的分支。GitHub 上的分支也可以在 PR 頁面刪掉。

主線永遠是能用的版本；新的嘗試都在分支上進行，檢查過才合併。

讓 AI Agent 在這套規則裡工作

現在你有了一整套安全網，可以放心讓 Claude Code 動手了。在 CLAUDE.md 加上 Git 的規則：

## Git
- 不要直接在 main 上修改。每個任務開一條新分支。
- 每完成一個小步驟就 commit，說明用中文寫清楚做了什麼。
- commit 前執行 uv run pytest 和 uv run mypy .，都通過才 commit。
- 不要使用 git push --force，不要改寫已經推上去的歷史。
- 不要 commit expenses.csv、.env 或任何個人資料。

之後你可以這樣交代任務：「開一條新分支，實作只看本月份的報表，完成後推上 GitHub 開一個 Pull Request。」Claude Code 能幫你執行這些 Git 指令（開 PR 通常會用到 GitHub 的命令列工具 gh，第一次使用需要你自己登入）。你要做的，是在 PR 頁面逐行檢查它的修改，就像主管審核新同事的工作。

回頭看看這個單元

六堂課前，你的記帳工具是一個 60 行的檔案。現在它有：

1. 模組與套件：每個檔案只管一件事，要改哪裡一眼就知道
2. uv 與 pyproject.toml：任何電腦都能一個指令重建環境
3. 例外處理：出錯時好好說明，資料不會悄悄不見
4. 型別提示與 mypy：資料格式寫得清清楚楚，執行前就抓到錯
5. pytest 自動測試：一個指令驗收所有功能
6. Git 與 GitHub：每一步都能檢查、都能回頭

再加上一份 CLAUDE.md，把這些規則寫給每一位 AI 同事看。

這些不只是「工程師的規矩」。它們讓任何接手的人，包括三個月後的你和每一個 AI Agent，都能看懂、敢修改、改壞了也收得回來。這就是 AI 時代，寫程式的人最值錢的基本功。