GitHub工作流
一句話定義
把每個改動隔離在 feature branch、透過 PR 走 review 進主分支、用 squash-merge 維持主分支歷史簡潔的標準 Git 協作流程；個人專案 / 開源專案 / 公司專案皆通用，是
add commit push一把梭直推主分支的反模式。
核心要點
元命題
「主分支屬於專案 / feature branch 屬於個人」——即使同一人持有兩者，這兩個分支扮演不同角色。流程的整個設計都圍繞這個角色分離。
Remote / Local Git / Disk 三層心智模型
教學版本把本地拆兩層，這樣三個事實能各自定位（2026-05-01-十分鐘GitHub工作流 教程版）：
| 層 | 角色 | 你看到什麼 |
|---|---|---|
| Remote | GitHub 上的共享倉庫 | 別人也看得到的 branch、PR、issue |
| Local Git | 本地 .git/ 目錄 | 你告訴 Git 的所有資訊——commit 歷史、本地 branch |
| Disk | 工作目錄的檔案 | 編輯器打開時看到的原文件實際樣貌 |
三層分離才能解釋這些日常困惑：
- 「我改了檔案但 Git 不知道」 → 改動只在 Disk，沒進 Local Git
- 「我 commit 了但 GitHub 沒變」 → 改動只在 Local Git，沒 push 到 Remote
- 「
git checkout main後我的修改不見了」 → checkout 把 Local Git 的 branch 同步給 Disk，你的 myfeature 改動還在 Local Git 裡
正規版本還有 staging area（暫存區）作為 Local Git 與 Disk 之間的緩衝層，是
git add的目的地；教程刻意省略以降低新手認知負擔。
七步 Happy Path
從 clone 到 PR 的完整正向流程：
| # | 命令 | 作用 | 同步狀態 |
|---|---|---|---|
| 1 | git clone <url> | Remote → Local Git → Disk | 三層一致 |
| 2 | git checkout -b myfeature | 從當前 branch 複製出新 feature branch | Local Git 多一個 branch |
| 3 | 編輯檔案 → git diff | 強烈建議下一步前先 diff | Disk 改動，Local Git 未知 |
| 4 | git add <files> | 改動進暫存區（告訴 Git「這些我想 commit」） | Local Git 半知道 |
| 5 | git commit | 真正寫進 Local Git | Local Git 多一個 commit |
| 6 | git push origin myfeature | Local Git → Remote | GitHub 多一個 branch |
| 7 | 在 GitHub 介面建 [[Pull-Request | PR]] | 請求把 myfeature 改動 pull 進 main |
同步 main 更新（Rebase 流）
當你還在 feature branch 開發時，main 又有新 commit 進來，要把新 main 整合到你的 feature branch：
git checkout main— 切回 main，Disk 變回 main 的狀態git pull origin main— 把遠端 main 同步到本地 main + Diskgit checkout myfeature— 切回你的 feature branchgit rebase main— 把你的 commit 先扔旁邊 → 套上最新 main → 再把你的 commit 接回去git push origin myfeature -f— rebase 改寫了歷史，必須-f（force）才能推回
遇到 rebase conflict：手動選擇要哪一段代碼，解完 →
git add→git rebase --continue。
Rebase 而非 Merge 的好處
| 操作 | feature branch 看起來像 | main 歷史 |
|---|---|---|
| Rebase main | 「在最新的 main 上做的」（線性） | 乾淨、像一個人寫的 |
| Merge main | 保留分叉，多一個 merge commit | 多分叉、雜訊較高 |
rebase 後 commit hash 會改變，這是必須 push -f 的原因（強推遠端覆蓋本地改寫過的歷史）；故 rebase 適合自己的 feature branch（沒人依賴你的 hash）/ 不適合公開的長壽 branch（會打亂他人本地）。
Pull Request 與 Squash-Merge
PR = 「請項目主人把我這個分支的改變給 pull 到專案裡去」——詳見 Pull-Request。
合併 PR 時 GitHub 提供三種策略，預設選擇是 Squash and Merge：
| 策略 | feature branch 多個 commit 進 main 後變成 | 何時用 |
|---|---|---|
| Squash and Merge | 一個 clean commit | 預設——main 每個 commit 都正常工作 |
| Create a Merge Commit | 全部保留 + 一個 merge commit | 想保留 feature 開發過程歷史 |
| Rebase and Merge | 全部保留為線性追加 | 開發過程已是乾淨的 commit-by-commit 故事 |
為何預設 squash：feature branch 上常有「fix typo / 格式調整 / debug 嘗試 / WIP」等雜訊 commit；這些不該污染 main。目標：main 上每個 commit 都是正常工作的——這是 main 可以隨時 deploy / 隨時 checkout 任何點都不壞的根據。
PR 合併後的清理三步
很多人忽略的尾巴：
- GitHub 上按「Delete branch」按鈕刪遠端 feature branch
- 本地：
git checkout main→git branch -d myfeature刪本地 branch - 本地：
git pull origin main把剛被 squash 進的 update 同步回本地 main + Disk
完成後 Local Git / Disk / Remote 三者再次完全一致，回到 clone 後的乾淨狀態。
反模式：add commit push 一把梭直推 main
許多新手習慣 git add . && git commit && git push 直接打到 main。教程明確指出：
「在任何一個有一點點成熟度的項目裡，都不可能讓所有的程序員都在那 add commit push 一把梭——這種工作流程會讓你的項目管理崩潰的。」
直推 main 的問題：(a) 一個壞 commit 直接弄壞所有人；(b) 沒有 review 流程；(c) commit 歷史成雜訊；(d) 多人推同一 branch 必然衝突 / 重做。
與其他概念的關係
- Pull-Request — 是本工作流的核心介面層；不是 Git 原生功能而是 GitHub / GitLab / Bitbucket 等託管平台在 Git 之上加的 review + 合併機制。
- Code-Review — 是本工作流的品質治理層：feature branch 和 PR 提供場域，reviewer 判斷這個改動是否真的改善 codebase health。
- Git — 本工作流是 Git 命令的具體編排：clone / checkout -b / diff / add / commit / push / pull / rebase / branch -d 的 happy path 串起來；branch 廉價（O(1) 指標）是這套流程能成立的基礎。
- GitHub — PR 介面 + Squash and merge / Delete branch 按鈕是這套工作流的 UI 元件；不用 GitHub（GitLab / Bitbucket / Gitea）也有同名 / 同形式的介面。
- AI輔助開發 — feature branch 隔離 + diff 檢查 + PR review 是 AI agent（如 Claude-Code）大量產出代碼時的安全網與技術債閘門；本工作流是 AI 輔助開發進入成熟團隊的前置紀律。
- 程式碼風格指南 — PR 是 style guide 的最後一道把關：再短的指南也需要在 PR review 時被人或 hook 確認；squash-merge 的「main 每個 commit 都正常工作」原則直接對位 程式碼風格指南 Golden Rule「每一行程式都看起來像同一個人寫的」——squash 把多人 / 多次嘗試的雜訊收斂成單一作者外觀。
相關來源
- 2026-05-01-十分鐘GitHub工作流 — vault 中第一份系統處理 GitHub 工作流的來源；以「Remote / Local Git / Disk」三層心智模型 + 七步 happy path + rebase 同步流 + squash-merge + 清理三步介紹完整流程
- 2026-05-06-Google-Code-Review — 補入 PR review 的品質判準、速度要求與 comment 溝通規則，讓本工作流從操作流程擴展到工程治理
備註
建頁理由：作為 Git / GitHub 在實際協作場景下的標準操作流程，比兩個 entity 更高一層的方法論；獨立成概念而非併入任一 entity。理由：(1) 是跨工具的方法論（GitHub Flow / GitLab Flow / Gitea PR 工作流形式都類似）；(2) 是 AI輔助開發 場景的關鍵前置紀律；(3) 累積方向多元（替代工作流 git-flow / trunk-based / monorepo 對位、conventional commits 等規範對位、AI agent 自動 PR 流程的具體用例）。
未來累積方向：(a) 與 git-flow / trunk-based development / monorepo 工作流對位；(b) Conventional Commits / semantic-release 等命名規範累積；(c) Branch protection rules / CODEOWNERS / required reviews 等治理層；(d) Stacked PRs / Graphite / Spr 等進階流程工具；(e) AI agent（Claude-Code / Cursor / Aider）自動發 PR 的具體用例累積；(f) 開源專案如何用此工作流接受外部 PR（CONTRIBUTING.md / Issue Templates / DCO 簽署等）。