---
title: "09 - 實戰工作流範例"
type: note
specialty: Programming
tags: [git-github, 09-實戰工作流範例, workflow]
---

# 09 - 實戰工作流範例

← [[08-指令速查表]] | 回到 → [[00-Index]]

---

> 前面 01–08 把指令逐項教過了。這一篇用**這個筆記庫真實的工作流**當案例，
> 把零散指令串成一條「人＋多個 AI 同時安全協作」的完整流程。
> 你會看到：自動同步、`pull --rebase`、feature branch、自動部署、多代理 reconcile、重試退避——全部一次到位。

---

## 🎯 真實案例：一個半自動同步的知識庫 repo

這個 repo 不是普通的個人專案，而是**同時被多方寫入**：

| 角色 | 在做什麼 | 怎麼推 |
|------|---------|--------|
| **使用者**（人） | 在 Obsidian 裡念書、寫筆記 | `obsidian-git` 外掛**每 ~10 分鐘自動** commit/pull/push |
| **AI（Claude Code / Codex）** | 在 sandbox clone 這個 repo、補新筆記 | 完工後手動 pull --rebase → push |
| **Cloudflare Pages** | 把 repo 當成網站來源 | 偵測到 `main` 有新 commit 就**自動重建上線** |

換句話說：**同一個 `main` 分支，隨時可能被「人的自動同步」「另一個 AI」同時推新 commit。**
這正是 Git 協作最容易出事的場景——而下面這套流程就是用來安全駕馭它的。

---

## 🧩 三個並行寫入者，怎麼不打架？

### 寫入者 1：obsidian-git 的自動備份

使用者一邊念書，外掛就在背景默默工作，commit 訊息長這樣：

```
vault backup: 2026-06-24 14:32:01
vault backup: 2026-06-24 14:42:03
vault backup: 2026-06-24 14:52:01
```

→ 意義：**遠端 `main` 每 10 分鐘就可能多一批新 commit**。你 clone 下來的版本，幾分鐘後就「過時」了。

### 寫入者 2：AI 在 sandbox 工作

AI 通常被指派去**建立新檔案**或**只改特定資料夾**（例如只動 `Programming/Git-GitHub/`、
或只動 `_wiki_meta/`）。這是刻意的「**天然分工**」：

> 只要人和 AI 改的是**不同檔案**，rebase 時就不會撞同一行 → 自動乾淨合併、無痛。

### 寫入者 3：另一個 AI（Codex）也在推 main

在姊妹專案裡，**Codex 持續往 `main` 推 commit**，Claude 也同時在開發。
兩個 AI 共用一個 `main`，所以**合併前一定要先把對方的進度抓下來 reconcile**：

```bash
git fetch origin main
git merge origin/main     # 通常是附加式、乾淨的合併
```

---

## 🔁 核心招式：push 前一律 `git pull --rebase`

因為遠端隨時在動，**絕不能埋頭 commit 完就直接 push**（多半會被拒）。
鐵則是：**push 之前先 rebase，把遠端最新進度墊在自己 commit 底下。**

```bash
# 標準收尾流程（每次要 push 前都這樣做）
git pull --rebase origin main
# ↑ 把遠端（人的自動備份 + 別的 AI）最新 commit 拉下來，
#   再把自己的 commit 重放在最上面 → 歷史保持直線

git push origin main
```

- **rebase 乾淨**（動到不同檔案）→ 自動完成，直接 push，無感。
- **rebase 撞衝突**（= 跟使用者改到**同一檔同一區**）→ **停手，不要硬解**。
  回報是哪個檔衝突、兩邊內容都保留，交給使用者裁定。**絕不可覆蓋掉使用者的筆記。**

> [!warning] 為什麼不直接 `git push --force`？
> 因為遠端那些 `vault backup` 是使用者真實的念書成果。force push 會把它們**整批抹掉**。
> 在這種多方寫入的 repo，force push = 災難。永遠用 rebase 疊上去，不要覆蓋。

---

## 🌿 完整流程：AI 接到「補一篇筆記」任務

把前面所有概念串起來，一次任務從頭到尾長這樣：

```bash
# 0. 拿到最新的起點
git clone git@github.com:dirtywolf1213/Obsidian-med-note.git
cd Obsidian-med-note

# 1. 開一條 feature 分支來做（不直接動 main）
git switch -c feature/git-tutorial-enhance

# 2. 做事：盡量「建新檔」或只改「特定資料夾」（降低衝突）
#    ... 寫筆記、改檔案 ...

# 3. commit（訊息講清楚改了哪篇、來源為何）
git add .
git commit -m "加強 Git 教學系列、新增實戰工作流範例"

# 4. 切回 main，先把別人的進度 reconcile 進來
git switch main
git pull --rebase origin main      # 抓使用者自動備份 + 其他 AI 的 commit

# 5. 把 feature 分支併回 main（Obsidian 開的是 main）
git merge feature/git-tutorial-enhance

# 6. push 前再 rebase 一次（這段時間遠端可能又動了）
git pull --rebase origin main
git push origin main               # → 觸發 Cloudflare Pages 自動重建上線

# 7. 清掉用完的分支
git branch -d feature/git-tutorial-enhance
```

> 第 6 步又 rebase 一次不是多餘：第 4 到第 6 步之間可能又過了幾分鐘，
> obsidian-git 很可能已經推了新的 `vault backup`。**push 前永遠再確認一次。**

---

## 🚀 push main 就上線：自動部署

這個 repo **本身就是網站的來源**（用 Quartz v4 靜態網站產生器）：

```
push 到 main
   ↓
Cloudflare Pages 偵測到變更
   ↓
自動重新 build（把 .md 轉成靜態網頁）
   ↓
幾分鐘後新內容上線
```

意義對寫筆記的人：

- **不用手動部署**，push 完就會自己更新網站。
- 但也因此——**壞掉的東西也會自動上線**。所以推之前要顧好：
  - frontmatter 必須是**合法 YAML**（壞 YAML 會讓整站該次 build 失敗）。
  - 圖片用 Obsidian 嵌入語法 `![[檔名.png]]`（不要用 `![](相對路徑)`，網頁會破圖）。

---

## 🔂 網路不穩怎麼辦：retry + 指數退避

sandbox 環境的 push 偶爾會因網路抖動而失敗。對策是**重試，並逐次拉長等待時間**
（指數退避 exponential backoff），而不是瘋狂連續重試：

```
push 失敗 → 等 2s → 重試
還失敗   → 等 4s → 重試
還失敗   → 等 8s → 重試
還失敗   → 等 16s → 重試
```

概念性的腳本寫法：

```bash
for delay in 2 4 8 16; do
  if git push origin main; then
    break                      # 成功就跳出
  fi
  sleep "$delay"               # 失敗就等久一點再試
  git pull --rebase origin main   # 重試前再同步一次遠端
done
```

> 每次重試前都 `pull --rebase`，是因為「失敗的這段時間」遠端可能又被推了新東西。

---

## ✅ 這套流程為什麼安全？回顧

| 風險 | 對策 |
|------|------|
| 遠端隨時被自動同步推新 commit | push 前一律 `git pull --rebase origin main` |
| 人和 AI 改到同檔造成衝突 | AI 盡量**建新檔 / 只改特定資料夾**（天然分工） |
| 真撞衝突 | **停手不硬解**，保留兩邊、交人裁定，絕不覆蓋使用者筆記 |
| 多個 AI 共用 main | 合併前 `git fetch origin main && git merge origin/main` reconcile |
| push 被拒 / 網路抖動 | retry + 指數退避（2s/4s/8s/16s） |
| 壞內容自動上線 | push 前確認 YAML 合法、圖片用 `![[ ]]` |

**一句話總結：** 別人隨時在動 `main`，所以「先把別人的疊進來，再把自己的放上去，撞到就停手問人」。

---

## 🔗 相關章節

- [[05-Push與Pull]] — `pull --rebase`、merge conflict、HTTPS/SSH 的基礎
- [[06-分支管理]] — feature branch、merge vs rebase、PR 流程
- [[07-常見問題與解法]] — 自動同步打架、reflog 救命、rebase 中途放棄

---

## 📌 小結

- 這個 repo 是**人＋多個 AI＋自動部署**同時寫一個 `main` 的真實協作場景。
- 核心是 `git pull --rebase origin main`：**先疊別人的，再放自己的**。
- 降衝突靠**分工**（建新檔 / 只改特定資料夾），撞衝突就**停手交人**，不硬解、不 force。
- push `main` = 自動部署上線，所以推之前要顧好 YAML 與圖片寫法。
- 網路失敗用 **retry + 指數退避**，每次重試前再同步一次。

---

← [[08-指令速查表]] | 回到 → [[00-Index]]