Git × Claude Code — 版控入門指南

SECTION 01

版控到底在解決什麼問題？

先建立直覺，再學工具。

你有沒有遇過這些情況：

📁

檔名地獄

專案資料夾裡有 final.js、final_v2.js、final_真的最後版.js

版控讓每次「儲存進度」都有時間戳記與說明，你永遠知道回到哪個版本，不需要亂取檔名。

▸ 點開看解法

💥

改爛了回不去

改了一堆東西，搞壞了，但不知道改了哪裡

Git 保存每一個「存檔點」。任何時候都可以查看「我改了什麼」，或直接回到上一個正常版本。

▸ 點開看解法

🤝

多人互蓋

兩個人同時改同一支程式，後存檔的人把前面的蓋掉

Git 的 branch（分支）機制讓每個人在自己的空間工作，完成後再「合併」，衝突也會明確標示出來。

▸ 點開看解法

❓

誰改的？

上線後出問題，不知道是誰、什麼時候加了那行程式碼

每一個 commit 都記錄作者、時間、說明。追問題像偵探一樣，有完整紀錄可查。

▸ 點開看解法

一句話理解版控 Git 就是一個超強的「存檔系統」，它記住你每一次存檔的內容、時間、說明，還能讓多人同時在不同分支工作。

Git vs GitHub — 這兩個不一樣

名詞	是什麼	比喻
Git	版本控制工具，裝在你的電腦上	你自己的存檔系統
GitHub / GitLab	存放程式碼的雲端平台	共用的 Google Drive
Repository (Repo)	一個專案的所有檔案 + 歷史紀錄	一個專案資料夾（含所有版本）

SECTION 02

五個核心概念

點開每張卡片看詳細說明與比喻。

📸

commit

儲存一個「存檔點」，並附上說明

比喻：打電動存檔。每次完成一個功能或修完一個 bug，就 commit 一次。

一個好的 commit 只做「一件事」，說明清楚「做了什麼」而不是「改了哪些檔案」。

❌ update files
✅ fix: 修正登入頁面密碼驗證邏輯

▸ 點開看詳情

🌿

branch

建立一個平行的工作空間，不影響主線

比喻：複印一份文件去修改，主要那份不動。

通常有一個 main 分支是「正式版」，每個新功能在自己的分支開發完再合併。

常見命名：
feat/login-page — 新功能
fix/api-timeout — 修 bug
chore/update-deps — 維護工作

▸ 點開看詳情

🔀

merge / PR

把分支的修改合回主線

比喻：校稿完畢，把修改後的那份合回原本文件。

PR（Pull Request）是正式提交合併申請，讓團隊其他人 code review（審查）後才合入。

這是協作最重要的環節，不要跳過。

▸ 點開看詳情

⬆️

push / pull

本地 ↔ 雲端的同步動作

push：把本地的 commit 上傳到 GitHub
pull：把 GitHub 最新的版本下載到本地

好習慣：每次開始工作前先 pull，確保你在最新版本上工作，避免衝突。

▸ 點開看詳情

💥

conflict

兩個分支都改了同一行，Git 不知道要保留哪個

別慌！這是正常現象。Git 會標記出衝突的地方：

<<<<<<< HEAD
你的版本
=======
別人的版本
>>>>>>> feat/xxx

你需要手動決定「留哪個」，或者兩個都保留、重新整理。用 Claude Code 處理衝突非常方便。

▸ 點開看詳情

📋

staging area

commit 前的「準備區」，可以選擇要提交哪些修改

Git 有三個區域：

1. 工作目錄 — 你正在改的檔案
2. Staging（暫存區） — 已選擇要 commit 的修改
3. Repository — 已存下來的歷史紀錄

用 git add 把修改放進 staging，再用 git commit 正式存檔。

▸ 點開看詳情

// 完整資料流示意

你的電腦
工作目錄

→ git add →

Staging Area
準備提交

→ git commit →

Local Repo
本地歷史

→ git push →

GitHub
雲端備份

GitHub

→ git pull →

Local Repo

自動同步到

工作目錄

* Claude Code 會幫你處理大部分的 git add / commit / push 指令，你只需要確認操作正確。

SECTION 03

用 Claude Code 操作版控

不用背指令，用自然語言描述你要做什麼。

核心心法 Claude Code 幫你執行 git 指令，但你需要知道「為什麼」，才能確認它做的是你想要的。

日常開發標準流程

1

開始工作前：拉最新版本

告訴 Claude Code：「幫我 pull 最新版本，確認我在 main branch 上」

2

建立功能分支

告訴 Claude Code：「建立一個新分支，名稱 feat/[你的功能名稱]，然後切換過去」

3

開發、邊做邊存

完成一個小功能或修完一個問題，就 commit 一次。告訴 Claude Code：「把這次的修改 commit，說明是『fix: 修正 XXX 問題』」

4

Push 到 GitHub

告訴 Claude Code：「把這個分支 push 到 GitHub」

5

開 PR 請人 Review

到 GitHub 網頁開 Pull Request，填寫說明，指定 reviewer。

常用自然語言指令範例

    Claude Code 對話範例
    # 查看目前狀態

    你：幫我看一下目前 git 狀態，有哪些檔案被修改了？

    # 存檔

    你：把所有修改 commit，說明是「feat: 新增用戶登入功能」

    # 切換分支

    你：幫我切換到 main 分支，然後 pull 最新版本

    # 查看歷史

    你：顯示最近 5 個 commit 的紀錄

    # 比較差異

    你：比較我現在的修改和上一個 commit 有什麼不同？

⚠️ 注意事項 Claude Code 執行 git 操作前通常會顯示指令讓你確認。請務必讀一下再按確認，特別是 push、reset、merge 等動作。

SECTION 04

團隊協作規範

好的習慣讓整個團隊都好過。

Commit Message 格式

採用 Conventional Commits 格式，讓歷史紀錄一目了然：

前綴	用途	範例
`feat:`	新功能	`feat: 新增訂單匯出 CSV 功能`
`fix:`	修 Bug	`fix: 修正分頁在 Safari 顯示異常`
`docs:`	文件修改	`docs: 更新 README 安裝說明`
`refactor:`	重構（不改功能）	`refactor: 整理 API 模組架構`
`chore:`	雜事、設定更新	`chore: 更新 Node.js 版本`
`test:`	測試相關	`test: 新增登入模組單元測試`

Branch 命名規則

    feat/[功能名稱]   — 新功能開發

    fix/[問題描述]    — Bug 修復

    hotfix/[問題]     — 緊急修復（直接影響正式環境）

    chore/[說明]      — 維護、設定、雜務

不該做的事

🚫

直接 push 到 main

main 是正式版。永遠在自己的分支開發，透過 PR 合入。

🚫

commit 裡包含密碼

API key、密碼絕對不能放進 git。用 .env 檔案 + .gitignore 處理。

🚫

一次 commit 改太多

一個 commit 只做一件事。大範圍修改要拆成多個小 commit。

🚫

不寫說明就 commit

「update」、「fix」這種說明沒有意義。寫清楚「修了什麼」、「為什麼改」。

💡 好習慣養成 每天下班前，確認工作中的修改都已 commit 並 push 到 GitHub。這樣明天電腦壞掉、換人接手，都沒問題。

SECTION 05

常見狀況 & 解法

遇到問題不要慌，大部分都有解。

😱

commit 了但寫錯訊息

剛剛 commit，但說明打錯字

告訴 Claude Code：「幫我修改最後一個 commit 的說明，改成『...』」

它會執行：git commit --amend -m "新說明"

⚠️ 注意：如果已經 push 了，修改後要用 force push，需要小心。

▸ 點開看解法

😰

不小心 commit 了不該 commit 的東西

把測試用的亂碼或 .env 檔案 commit 進去了

告訴 Claude Code：「幫我把上一個 commit 撤回，保留修改在工作目錄」

它會執行：git reset HEAD~1

然後加好 .gitignore 再重新 commit 正確的內容。

▸ 點開看解法

😤

merge 衝突不知道怎麼解

Pull 或 merge 的時候出現 CONFLICT

告訴 Claude Code：「我遇到 merge conflict，幫我看一下衝突在哪裡，解釋應該怎麼解」

Claude Code 會顯示衝突的程式碼，你決定保留哪個版本，它再幫你完成 merge commit。

▸ 點開看解法

😵

改爛了想回到上一個正常版

改了一堆，搞壞了，想全部放棄

告訴 Claude Code：「把工作目錄的所有修改全部還原，回到上一個 commit 的狀態」

它會執行：git checkout -- . 或 git restore .

⚠️ 這個操作不可逆，確定要放棄所有未 commit 的修改才執行。

▸ 點開看解法

🤔

不知道現在在哪個分支

忘記自己在哪個分支、有沒有 commit 沒 push

告訴 Claude Code：「告訴我目前的分支狀態，有哪些修改還沒 commit，有哪些 commit 還沒 push」

它會執行 git status 和 git log --oneline 幫你整理清楚。

▸ 點開看解法

🔍

想找某個功能是誰寫的

這行 code 是哪個 commit 加的？是誰改的？

告訴 Claude Code：「用 git blame 查一下 [檔案名稱]，看每一行是誰在哪個 commit 加的」

或：「幫我搜尋哪個 commit 裡有關鍵字 'XXX'」

▸ 點開看解法

SECTION 06

觀念小測驗

確認你已經掌握核心概念。共 5 題。

Q1 / 5開發新功能時，正確的做法是？

Q2 / 5以下哪個 commit message 最好？

Q3 / 5git push 是做什麼？

Q4 / 5遇到 merge conflict 應該怎麼做？

Q5 / 5以下哪個不該放進 git commit？