Git bare repo：直接把家目錄當 work tree

bare repo 的概念是在家目錄建一個沒有工作目錄的 Git 倉庫，然後用 alias 指定 --work-tree=$HOME，讓 Git 直接追蹤家目錄下的檔案，不需要 symlink、不需要額外工具。

初始化：

1git init --bare "$HOME/.dotfiles"

在 shell 配置裡加一行 alias：

1alias dotfiles='git --git-dir="$HOME/.dotfiles" --work-tree="$HOME"'

之後所有 dotfile 操作都透過這個 alias：

1dotfiles add ~/.zshrc
2dotfiles commit -m "add zshrc"
3dotfiles remote add origin git@github.com:you/dotfiles.git
4dotfiles push -u origin main

第一件要做的事是隱藏未追蹤檔案。家目錄底下有成千上萬個檔案，如果不設定這一行，dotfiles status 會列出所有未追蹤的東西：

1dotfiles config --local status.showUntrackedFiles no

新機器還原的流程：

1git clone --bare git@github.com:you/dotfiles.git "$HOME/.dotfiles"
2alias dotfiles='git --git-dir="$HOME/.dotfiles" --work-tree="$HOME"'
3dotfiles config --local status.showUntrackedFiles no
4dotfiles checkout

checkout 這步會把 repo 裡的檔案寫到家目錄。如果家目錄已經有同名檔案（例如系統預設的 .bashrc），checkout 會失敗並列出衝突檔案，需要先手動備份或刪除。

bare repo 適合配置量少、只管一台機器、不想安裝任何額外工具的人。它的限制是：概念對 Git 初學者不直覺（bare repo + work-tree 的組合不常見）、沒有模組化的概念（無法選擇性安裝某些配置）、多 profile 支援弱（不同機器要不同配置時只能靠 branch，長期維護困難）。

GNU Stow：symlink 農場管理器

Stow 的概念是把 dotfile 集中放在一個普通目錄（如 ~/dotfiles），然後用 stow 指令在家目錄建立 symlink。stow 的核心規則是：package 目錄內的路徑結構，就是安裝後相對於目標目錄的路徑結構。

1# 安裝 stow
2# macOS
3brew install stow
4# Arch Linux
5sudo pacman -S stow
6# Ubuntu/Debian
7sudo apt install stow

以 zsh 配置為例，目錄結構長這樣：

1~/dotfiles/zsh/.zshrc

執行 stow zsh 後，stow 會在 $HOME 建一個 symlink：

1~/.zshrc -> ~/dotfiles/zsh/.zshrc

對於放在 ~/.config/ 底下的工具（XDG 規範），目錄結構映射同樣的邏輯：

1~/dotfiles/nvim/.config/nvim/init.lua
2~/dotfiles/nvim/.config/nvim/lua/plugins.lua

執行 stow nvim 後：

1~/.config/nvim -> ~/dotfiles/nvim/.config/nvim

stow 會自動判斷該 symlink 整個目錄還是個別檔案——如果目標目錄不存在或目錄內所有檔案都由同一個 package 管理，stow 會 symlink 整個目錄（folding）；如果目標目錄已有其他檔案，stow 會展開（unfolding）成逐檔 symlink。

初始化和日常操作：

 1# 初始化
 2mkdir ~/dotfiles && cd ~/dotfiles
 3git init
 4git remote add origin git@github.com:you/dotfiles.git
 5
 6# 把現有 .zshrc 搬進 dotfiles
 7mkdir -p ~/dotfiles/zsh
 8mv ~/.zshrc ~/dotfiles/zsh/.zshrc
 9cd ~/dotfiles && stow zsh
10# 現在 ~/.zshrc 是一個 symlink，指向 ~/dotfiles/zsh/.zshrc
11
12# 日常修改：直接編輯，symlink 透通
13vim ~/.zshrc  # 實際編輯的是 ~/dotfiles/zsh/.zshrc
14cd ~/dotfiles && git add -A && git commit -m "update zshrc"
15
16# 新機器還原
17git clone git@github.com:you/dotfiles.git ~/dotfiles
18cd ~/dotfiles && stow zsh git nvim tmux

批次安裝所有 package：

1cd ~/dotfiles
2# stow 會把每個頂層目錄當成一個 package
3stow */

移除某個 package 的 symlink：

1cd ~/dotfiles && stow -D nvim

stow 適合中等複雜度的配置管理。它的優勢是模組化（每個工具獨立一個 package、可選擇性安裝）和概念直覺（目錄結構就是安裝後的樣子）。它的限制是只管 symlink 映射，不管套件安裝；跨 OS 的路徑差異（macOS 和 Linux 某些工具的配置路徑不同）需要自己處理；stow 也不管 file permission——需要 0600 權限的 secret 檔（SSH private key、API token config）靠 symlink 繼承來源檔案權限，不能在部署過程中自動設定。

yadm：bare repo 的升級版

yadm 包裝了 Git bare repo 的操作，加上三個 bare repo 缺少的能力：alternate files（依 OS、hostname、甚至 user 條件選擇安裝不同版本的配置檔）、encrypt（用 GPG 或 OpenSSL 加密敏感檔案、不依賴外部密碼管理器）、bootstrap script（clone 後自動跑初始化）。

 1# 安裝
 2brew install yadm          # macOS
 3sudo pacman -S yadm        # Arch
 4
 5# 初始化（等同 git init --bare + 自動設定 alias）
 6yadm init
 7yadm remote add origin git@github.com:you/dotfiles.git
 8
 9# 操作方式跟 Git 完全一樣
10yadm add ~/.zshrc
11yadm commit -m "add zshrc"
12yadm push

Alternate files 的概念是在同一個 repo 裡放多個版本的同一個檔案，yadm 依條件決定用哪一個：

1~/.config/alacritty/alacritty.toml##os.Darwin
2~/.config/alacritty/alacritty.toml##os.Linux

macOS 上 yadm 自動 checkout Darwin 版本、Linux 上 checkout Linux 版本。比 stow 的 shell if-else 判斷更乾淨，比 chezmoi 的 Go template 學習曲線低。

yadm 適合想要 bare repo 的簡單性、但需要條件安裝或 secret 加密的人。它的限制是沒有 stow 的模組化概念（無法選擇性只安裝某些工具的配置）、沒有 chezmoi 的 template 細粒度（alternate files 是整個檔案切換，不是檔案內的段落條件）。

Chezmoi：多機器 dotfile 管理工具

Chezmoi 是專為 dotfile 管理設計的工具，原生處理 template、secret 管理和多機器差異。它把 dotfile 存在自己的 source directory（~/.local/share/chezmoi），用 chezmoi apply 把檔案實際寫入目標位置（不是 symlink，是複製）。

1# 安裝
2brew install chezmoi        # macOS
3pacman -S chezmoi           # Arch
4sh -c "$(curl -fsLS get.chezmoi.io)"  # 通用

基本操作：

 1# 初始化（會建立 source directory 和 Git repo）
 2chezmoi init
 3
 4# 加入現有配置
 5chezmoi add ~/.zshrc
 6chezmoi add ~/.config/nvim
 7
 8# 編輯（在 source directory 裡編輯，不是直接改家目錄的檔案）
 9chezmoi edit ~/.zshrc
10
11# 預覽差異
12chezmoi diff
13
14# 套用到家目錄
15chezmoi apply
16
17# 推上遠端
18chezmoi cd  # 進入 source directory
19git add -A && git commit -m "update" && git push

chezmoi 的核心優勢是 template。同一份配置檔在不同機器可以產生不同內容：

 1# chezmoi 的 source directory 裡，檔案名稱加 .tmpl 後綴
 2# dot_zshrc.tmpl
 3
 4export EDITOR="nvim"
 5
 6{{- if eq .chezmoi.os "darwin" }}
 7export HOMEBREW_PREFIX="/opt/homebrew"
 8eval "$($HOMEBREW_PREFIX/bin/brew shellenv)"
 9{{- end }}
10
11{{- if eq .chezmoi.os "linux" }}
12export PATH="$HOME/.local/bin:$PATH"
13{{- end }}

chezmoi apply 會根據當前機器的 OS 展開 template，macOS 上產生的 .zshrc 會包含 Homebrew 設定，Linux 上不會。

Secret 管理是另一個殺手功能。chezmoi 整合了 1Password、Bitwarden、pass、gopass、LastPass 等密碼管理器：

1# dot_gitconfig.tmpl
2[user]
3    name = Your Name
4    email = {{ (onepasswordRead "op://Personal/Git Config/email").value }}

chezmoi apply 時會即時從 1Password 拉值填入，secret 不會存在 Git repo 裡。

chezmoi 適合管理多台異質機器（macOS 工作機 + Linux 伺服器 + Linux 桌面 VM）且有 secret 需求的人。它的代價是學習曲線最陡——要理解 chezmoi 自己的目錄命名慣例（dot_ 前綴代表 . 開頭、private_ 前綴代表權限 0600）、template 語法（Go template）、以及「source directory 和目標位置是兩份獨立的檔案」這個心智模型。

選型判讀

選工具看三個維度：機器數量、OS 組合、secret 需求。

只有一台機器、配置簡單 — bare repo 或 stow 都夠用，差別在於你喜不喜歡 symlink 的管理方式。bare repo 最輕量，stow 多一層模組化。

多台同質機器（都是 macOS 或都是 Linux）— stow。配置檔在同 OS 間差異小，不需要 template，stow 的模組化讓你可以只在桌面機安裝 hyprland package、伺服器只裝 zsh + git + tmux。

多台異質機器（macOS + Linux）但 secret 需求不高 — stow 加上 OS 分流仍然可行，跨平台共用一個 Repo 會完整說明做法。

多台異質機器、需要條件安裝但不想學 template 語法 — yadm。alternate files 讓你依 OS/hostname 切換整個配置檔，內建 encrypt 處理 secret，Git 操作方式跟 bare repo 相同。

多台異質機器（macOS + Linux）、有細粒度 template 或密碼管理器整合需求 — chezmoi。檔案內的段落條件、跟 1Password/Bitwarden 的整合、private_ 前綴的 permission 管理是它存在的理由。

不確定 — 從 stow 開始。它的概念最直覺（目錄結構 = 安裝後位置）、遷移成本最低（要換到 yadm 是加一層 wrapper、要換到 chezmoi 時目錄結構的概念是相通的）。

開始之前，確認 SSH key 和 Git 已經設好、dotfile repo 已經 clone 到本機——這些前置步驟見環境建置的操作順序的階段一。

章節文章

跨分類引用

• → 模組零：Dotfile 心智模型：為什麼要管理、哪些東西該進 repo
• → 模組二：Shell 配置：目錄結構裡 zsh package 的具體拆法
• → 模組八：同步、Bootstrap 與環境重建：跨機器同步策略與 secret 管理

目錄結構設計

以 stow 為例的標準結構：

 1~/dotfiles/
 2├── zsh/
 3│   └── .zshrc
 4├── git/
 5│   ├── .gitconfig
 6│   └── .gitignore_global
 7├── ssh/
 8│   └── .ssh/
 9│       └── config
10├── nvim/
11│   └── .config/
12│       └── nvim/
13│           ├── init.lua
14│           └── lua/
15├── tmux/
16│   └── .config/
17│       └── tmux/
18│           └── tmux.conf
19├── hyprland/
20│   └── .config/
21│       └── hypr/
22│           └── hyprland.conf
23├── waybar/
24│   └── .config/
25│       └── waybar/
26│           ├── config.jsonc
27│           └── style.css
28├── scripts/
29│   └── install.sh
30├── Brewfile
31├── packages.txt
32├── .gitignore
33└── README.md

這些設計選擇的理由：

每個工具一個頂層目錄。stow 的 package 概念讓你可以選擇性安裝——伺服器不需要 hyprland 和 waybar，只 stow 需要的 package。即使不用 stow，這個分法也讓 repo 結構清晰：看頂層目錄就知道管了哪些工具。

目錄內路徑映射安裝位置。nvim/.config/nvim/init.lua 安裝後變成 ~/.config/nvim/init.lua。這個映射是 stow 的核心假設，但即使用 chezmoi 或 bare repo，維持同樣的思維讓目錄結構自解釋。

scripts/ 不是 stow package。scripts/install.sh 是 bootstrap 用的安裝腳本，不應該被 stow 到家目錄。它放在 repo 裡是為了讓新機器還原時有一個入口點可以跑。

Brewfile / packages.txt 記錄套件清單。配置檔只告訴工具「怎麼用」，但前提是工具已安裝。Brewfile（macOS 用 brew bundle）和 packages.txt（Linux 用套件管理器批次安裝）把「裝了什麼」也納入版控，讓新機器還原時不用靠記憶。

ssh/ 只放 config，不放私鑰。~/.ssh/config 記錄 SSH 連線設定（Host alias、ProxyJump 等），是有版控價值的配置。私鑰（id_ed25519、id_rsa）和公鑰不應進 dotfile repo，即使 repo 是 private。私鑰用密碼管理器或機器本地生成。

Git 工作流

dotfile repo 的 Git 工作流比一般程式碼專案簡單，因為通常只有一個人在用，branch 和 PR 的需求低。

日常修改。直接編輯配置（symlink 透通到 repo 裡的實體檔案），然後 commit：

1cd ~/dotfiles
2git add zsh/.zshrc
3git commit -m "zsh: add fzf integration"
4git push

新增一個工具的配置。先在 dotfiles 建好目錄結構，把現有配置搬進去，建 symlink，然後 commit：

1mkdir -p ~/dotfiles/alacritty/.config/alacritty
2mv ~/.config/alacritty/alacritty.toml ~/dotfiles/alacritty/.config/alacritty/
3cd ~/dotfiles && stow alacritty
4git add alacritty/ && git commit -m "add alacritty config"

新機器還原。整個流程應該能在幾分鐘內完成：

 1# 1. 裝 Git 和 stow（通常是最先裝的兩個東西）
 2# 2. clone
 3git clone git@github.com:you/dotfiles.git ~/dotfiles
 4# 3. 安裝套件
 5cd ~/dotfiles
 6brew bundle          # macOS
 7# 或
 8xargs sudo pacman -S < packages.txt  # Arch
 9# 4. 建 symlink
10stow zsh git nvim tmux ssh
11# 5. 重開 shell，配置生效

常見陷阱

私鑰進 repo。把 ~/.ssh/ 整個目錄（含 id_ed25519）推上 GitHub 是最危險的錯誤。即使事後刪除，Git 歷史裡仍然留有私鑰。做法是只追蹤 ~/.ssh/config，在 .gitignore 明確排除 *.pem、id_*。

缺少 .gitignore。很多工具會在配置目錄產生 cache、compiled 檔案、session 狀態。nvim 的 plugin/packer_compiled.lua、zsh 的 .zcompdump、tmux 的 resurrect/ 都不該進 repo。建 repo 時第一件事就是寫 .gitignore。

symlink 衝突。stow zsh 時如果 ~/.zshrc 已經存在且不是 symlink，stow 會拒絕操作。解法是先備份再安裝：

1mv ~/.zshrc ~/.zshrc.bak
2cd ~/dotfiles && stow zsh

路徑寫死。.zshrc 裡寫 source /Users/mac-eric/.nvm/nvm.sh 搬到 Linux 就壞了。改用 $HOME：source "$HOME/.nvm/nvm.sh"。配置檔裡每一處絕對路徑都是可攜性的隱患。

整包 .config 放一個 package。把 ~/.config 整個目錄當成一個 stow package 會喪失模組化的好處，而且衝突風險大幅增加。正確做法是每個工具拆開：nvim 一個、tmux 一個、hyprland 一個。

GitLab CE vs Gitea：選型判準

兩個主流的自建版本控制方案定位不同：

選型判準是團隊規模和需要的功能範圍。5 人以下、只需要 VCS + 輕量 CI 的團隊，Gitea + Drone 的組合維護成本低。10 人以上、需要 MR review + CI pipeline + Container Registry 一站到位的團隊，GitLab CE 的整合度值得它的資源消耗。

接下來以 GitLab CE 為主線說明（功能最完整），Gitea 的差異在各段附註。

GitLab CE 離線安裝

GitLab Omnibus 包把所有依賴打包成單一安裝檔，不需要在目標機器上 apt install 任何前置套件。

在外網機器下載安裝包

1# Ubuntu/Debian
2wget https://packages.gitlab.com/gitlab/gitlab-ce/packages/ubuntu/jammy/gitlab-ce_17.0.0-ce.0_amd64.deb/download.deb
3
4# RHEL/CentOS
5wget https://packages.gitlab.com/gitlab/gitlab-ce/packages/el/9/gitlab-ce-17.0.0-ce.0.el9.x86_64.rpm/download.rpm

把下載的 .deb 或 .rpm 透過內容搬運機制（USB、光碟、跨邊界傳輸站）帶進斷網環境。

在斷網機器安裝

1# Ubuntu/Debian
2sudo dpkg -i gitlab-ce_17.0.0-ce.0_amd64.deb
3
4# RHEL/CentOS
5sudo yum localinstall gitlab-ce-17.0.0-ce.0.el9.x86_64.rpm

離線設定

安裝後編輯 /etc/gitlab/gitlab.rb，把所有外部連線關掉：

 1# 設定內部域名（不是公網域名）
 2external_url 'https://gitlab.internal.example.com'
 3
 4# 關閉 Gravatar（頭像服務、需要外網）
 5gitlab_rails['gravatar_enabled'] = false
 6
 7# 關閉 usage ping（回報使用統計到 GitLab Inc）
 8gitlab_rails['usage_ping_enabled'] = false
 9
10# 關閉 version check
11gitlab_rails['gitlab_check_on_connect'] = false
12
13# 如果沒有內部 SMTP，用 sendmail 或關閉 email
14gitlab_rails['smtp_enable'] = false
15
16# TLS 憑證用內部 CA 簽發
17nginx['ssl_certificate'] = "/etc/gitlab/ssl/gitlab.crt"
18nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/gitlab.key"

1sudo gitlab-ctl reconfigure

Gitea 的離線安裝更簡單：下載單一二進位檔 gitea、設定 app.ini、用 systemd 管理即可。

升級策略

GitLab CE 的升級包也要從外部下載帶進來。升級前先備份（gitlab-backup create），升級路徑要按 GitLab 的版本跳級規則——不能任意跳版、某些大版本之間需要中繼版本。在斷網環境裡，每次升級要預先規劃中繼版本、一次帶進所有需要的安裝包。

CI Runner 離線設定

CI pipeline 在斷網環境裡跑的最大差異是 runner 不能即時拉依賴。

Runner 安裝與註冊

1# 下載 runner 二進位檔（外網下載、帶進來）
2# https://docs.gitlab.com/runner/install/linux-manually.html
3
4sudo gitlab-runner register \
5  --url https://gitlab.internal.example.com \
6  --token $RUNNER_TOKEN \
7  --executor docker \
8  --docker-image alpine:3.20

Executor 選擇

斷網環境推薦 shell executor（最少依賴）或 docker executor 搭配預拉好的 image。

Docker executor 的 image 管理

Docker executor 的每個 job 都基於一個 base image。斷網環境裡這些 image 必須預先存在於內網的 private registry：

1# runner 的 /etc/docker/daemon.json 指向內部 registry
2{
3  "insecure-registries": ["registry.internal:5000"],
4  "registry-mirrors": ["https://registry.internal:5000"]
5}

CI pipeline 裡用到的每個 image（build 用的 golang/node/php、lint 用的 tflint/checkov、deploy 用的 awscli）都要事先搬進內部 registry。

依賴快取

沒有 npm registry / PyPI / Maven Central 可以拉，CI job 的依賴安裝必須用本地來源：

1# .gitlab-ci.yml — 使用內部 Nexus 作為套件來源
2variables:
3  NPM_CONFIG_REGISTRY: "https://nexus.internal/repository/npm-proxy/"
4  PIP_INDEX_URL: "https://nexus.internal/repository/pypi-proxy/simple/"

或者把 node_modules / vendor 打包成 CI artifact 快取，避免每次 job 都重新安裝。

Git Bundle 跨邊界傳輸

某些斷網環境不允許直接 git push 到內網 GitLab（例如開發在外網、部署在內網）。Git bundle 是把 commit 歷史打包成單一檔案的機制：

1# 外網開發機：打包最近的 commit
2git bundle create changes.bundle main~5..main
3
4# 帶進斷網環境後
5git bundle verify changes.bundle
6git fetch changes.bundle main:incoming
7git merge incoming

bundle 檔案包含完整的 Git 物件（commit、tree、blob），可以通過任何檔案傳輸方式帶過邊界——USB、光碟、審批後的檔案傳輸閘道。

跨邊界傳輸的安全考量：bundle 的內容應該在傳入前被掃描（至少 git bundle verify），確認不包含預期外的分支或異常大的物件。某些高安全環境要求所有跨邊界檔案經過人工審批。

MR Review 流程

斷網環境的 MR（Merge Request）review 流程跟模組七：infra 走 PR 流程的原則相同——變更走 MR → CI 跑 plan → reviewer 看 diff + plan 輸出 → 合併 → apply。差別在於所有環節都在內網：

 1# .gitlab-ci.yml — Terraform plan 貼回 MR comment
 2plan:
 3  stage: plan
 4  script:
 5    - terraform init -plugin-dir=/opt/terraform/plugins
 6    - terraform plan -no-color -out=plan.tfplan | tee plan.txt
 7    - |
 8      curl --request POST \
 9        --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
10        --data-urlencode "body=$(cat plan.txt)" \
11        "https://gitlab.internal/api/v4/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
12  only:
13    - merge_requests

GitLab CI 的 merge_requests trigger 跟 GitHub Actions 的 pull_request 等價——MR 開啟或更新時自動跑 pipeline。

reviewer 在 GitLab 的 MR 頁面看 code diff + plan 輸出 comment，approve 後合併，合併觸發 apply pipeline。流程跟有網路時完全相同，只是所有元件（GitLab、runner、Terraform、provider plugin）都在內網。

時程與維護

GitLab CE 的主要維護成本在升級——斷網環境的升級不能一鍵 apt upgrade，要預先下載正確版本的安裝包帶進來。跳版規則讓這個過程比正常環境多一層規劃。

跨分類引用

• → 斷網環境的通用原則：內容搬運、離線套件管理的共通模式
• → 斷網環境的容器與映像管理：CI runner 的 Docker image 管理
• → 模組七：infra 走 PR 流程：MR review 流程的原則與護欄

本章寫的是「source / derived / external 三類產物的判讀框架」、跟「production deployment 怎麼處理 share + reproducibility 取捨」。對應到 hands-on 系列實際遇到的問題——為什麼 RAG demo 的 index.pkl 進 .gitignore、Hugging Face model weights 為什麼不能塞進 repo、prompt template 該怎麼版本管理。

跟 4.9 Production resource planning 對應「production 怎麼跑」、本章對應「production 怎麼版本控制 + 部署」。

本章目標

讀完本章後你能：

1. 用「source / derived / external」三分類判讀任何產物該不該進 git。
2. 看到 .gitignore 設計、能解釋每條規則的邏輯。
3. 在 reproducibility 跟 repo 大小之間做合理取捨。
4. 知道 derived / external 產物該用什麼機制 share（registry、build script、artifact storage）。

三類產物 framework

判讀問題：「刪掉重來、用什麼能 reconstruct 一模一樣？」

• 用人手寫 → source、必須 commit
• 用 build script + source → derived、commit manifest（如 lockfile）不 commit output
• 用 download script + URL → external、commit URL 不 commit content

這個 framework 跨任何技術 stack 都成立（不只 LLM）、但 LLM 應用尤其放大 derived / external 比例。

LLM 應用具體對應

Source（進 git）

Derived（不進 git、但 build path 進 git）

External（不進 git、用 manifest / registry）

External 跟 derived 的差別：external 來自 git 外的 source、derived 來自 git 內的 source。機制上都用同套路徑——manifest 進 git、實際 bytes 存 registry、避免大檔直接進 commit history。

為什麼 derived / external 不該進 git

每條限制有具體技術理由：

Size

Git 設計給 source code（小、純文字、頻繁 diff）。Derived / external 通常大、binary、不適合：

• Git 對 large binary 沒有有效 delta 演算法、每次小改 → 完整 copy 進 history
• Repo size 線性漲、clone 變慢、CI cache 爆炸
• GitHub 等服務有 file size 上限（GitHub 100 MB / file）

實例：scripts/rag-demo/index.pkl 3.7 MB、每次 corpus 改 → 重 ingest → 整檔變。Commit 100 次 = git history 多 370 MB。Clone 痛。

Reproducibility（反直覺）

直覺：「commit derived 保證每個 clone 都拿到一樣的 output」——錯。

實際：

• Derived 跟 build env 綁（Python 3.13 build 的 pickle 在 3.14 不一定能 load）
• Embedding index 跟 model version 綁（pull 不同 model 結果不同）
• 用舊 commit 的 derived 跑在新 env 反而比 rebuild 更脆弱

正確 reproducibility 機制：commit build instruction + lockfile、別人 rebuild 時用同樣輸入產同樣 output。

Update frequency mismatch

Source 改慢、derived 改快。content/ 加一句話、index.pkl 整個重建。如果都進 git：

• 90% 的 commit 是「rebuild artifact」、語意上不是真正的「source change」
• git log 看不出真正 source 改動
• diff review 被 derived noise 淹沒

Cost / Performance

CI / CD pipeline 通常自動 rebuild derived。不 commit 反而：

• Source-only PR 較易 review（沒 generated diff）
• CI build cache 重用、不需從 git 拉 derived
• Deploy artifact registry 跟 git 分離、各自 scale

LLM 應用 .gitignore 設計模式

LLM 應用典型 .gitignore 結構：

# === Source-side build output (derived) ===
# Compiled binaries
bin/
dist/
build/
*.pyc
__pycache__/

# Hugo / static site generators
public/
.hugo_build.lock
resources/

# RAG / vector indexes (regenerable)
scripts/rag-demo/index.pkl
*.pkl
*.index

# Embedding caches
.embedding_cache/
.vector_cache/

# === External-bound (don't commit, use manifest) ===
# Python deps (commit requirements.txt instead)
.venv/
venv/
env/

# Node deps
node_modules/

# Model weights / large files
*.safetensors
*.gguf
*.onnx
*.bin

# Datasets
data/raw/
data/processed/

# === Runtime / Local ===
# Logs
*.log
logs/

# OS / IDE
.DS_Store
.vscode/
.idea/

# Local secrets / API keys
.env
.env.local
*.key

# Temp / cache
*.tmp
.cache/

邊界 case 思考

幾個容易誤判的：

判讀 heuristic：

1這個檔案、半年後 production deploy 時要不要存在？
2├─ 要：source 或 manifest 進 git
3└─ 不要：runtime / 開發環境 only、用 .gitignore

三分類的退化情境

三分類是 default framework、實務上有幾類「該不該 commit 的判讀走兩條岔路」的情境、需要特別判讀：

• Generated client SDK in monorepo：protobuf / OpenAPI spec 產出的 client code 屬於 derived（從 .proto / .yaml 生）、但 monorepo 場景常 commit 進去、目的是「跨語言版本對齊 + CI 不用每次重生」。判讀：若 .proto / spec 改動頻率低 + 跨語言一致性比 build 速度重要、commit；變動頻繁就回到 derived 路徑。
• Jupyter notebook 的 output cell：技術上是 derived（執行 notebook 產出）、但語意上常被視為 source 的一部分（教學、demo、結果展示）。判讀：教學 / 展示 / 帶 figures 的 notebook 通常 commit 含 output；機械化的 batch run / CI notebook 走 derived、用 nbstripout 清掉 output 再 commit。
• Git LFS / git-annex 介於 commit 跟 manifest 之間：把大檔案 commit 進 git 但實際 bytes 存 LFS server、worktree 看起來像直接 commit、metadata 卻是 manifest pointer。判讀：適合「需要在 git history 中追蹤大檔案版本、但不想讓 repo 體積爆炸」的場景（如 game asset、訓練資料集 snapshot）。介於 commit 跟 dvc / S3 manifest 之間的折衷選項。
• Lockfile vs build artifact 的灰色帶：yarn-error.log 算 log（不 commit）還是 derived 但對 debug 重要（commit）？實務上多數選 .gitignore、但若團隊在 CI 失敗時要 reproduce 環境、保留少量 build log 也合理。

判讀原則：三分類給 default、灰色帶用「reproducibility + 變動頻率 + 團隊協作需求」三軸決定具體路徑。

Source / Derived / External 的 share 機制

不 commit 不代表不 share、只是用對的 channel。

Source share = git

直接 clone 即可。

Derived share 三種模式

1. Build script in repo：別人 clone 後跑 script 重建（本 blog 用這條：ingest.py 重建 index）
   • 優點：無外部依賴、self-contained
   • 缺點：每個 clone 都要重跑、累積 compute time
2. Release artifact：把 build output 上傳 GitHub Releases / S3、clone 後下載
   • 優點：clone 快、不用各自 rebuild
   • 缺點：要 maintain release pipeline、artifact 版本管理另立
3. Artifact registry：用 OCI registry、Docker registry、artifact storage（如 GitHub Packages / JFrog Artifactory）
   • 優點：production-grade、跨 team / 跨 org share
   • 缺點：複雜、配 auth、cost

選擇：小專案用 script、中型用 release、大型 / 多人 collaboration 用 registry。

External share = manifest

把「從哪下載 + checksum」commit 進 git、實際 content 不進。常見 manifest format：

Manifest 自己是 source（人寫、進 git）、它指向的 external content 不進 git（用 download script 取回）。

Prompt 跟 config 的版本控制

LLM 應用特有的問題：prompt template 是 source、但 prompt 改變影響行為跟 derived 改變不同。

Prompt + model 是一對組合、行為相依、改一個都要重 test。建議在 commit message / PR description 描述「這個 prompt 改動的 expected behavior change」、用規格層級的 review 對待、勿視為 trivial 小改。

Prompt 跟 evaluation 一起管理

進階做法：每個 prompt 配 evaluation set、commit 在同 PR：

1prompts/
2├── code_review.md           ← prompt template
3├── code_review_eval.json    ← input + expected output pair
4└── code_review_history.md   ← 改動記錄 + 對應 eval score

每次改 prompt、跑 eval、比較 score、進 commit message。這比「改完 push 看看效果」可控很多、是 prompt engineering 的基本姿勢。

Production deployment 的對接

本地 hands-on 跟 production 對應：

成熟的 LLM 應用部署 pipeline：

1Source change → git push
2              → CI triggered
3              → Build derived artifacts (index, container image)
4              → Run evaluation suite (prompt + model behavior tests)
5              → Push artifacts to registry
6              → Deploy with manifest pointing to specific artifact version
7              → Smoke test against production data
8              → Auto-rollback if metrics regress

每一步都要 commit-able 的 manifest。在可審計 / 多人協作 / 有 SLA 承諾的場景、「手動 build 完 ssh 進 prod scp」這種 ad-hoc 流程會破壞 reproducibility、出問題時無法 revert 到具體 build；早期 prototype / 單人專案 / 一次性 demo 可接受 ad-hoc 流程、進入 production 前再改成 manifest-based。Manifest 是 reproducibility 跟 audit 的基礎。

何時這篇會過時

不會過時的部分：

• Source / derived / external 三分類 framework
• 「commit manifest、不 commit content」核心原則
• .gitignore 通用模式
• Reproducibility 來自 build instruction、不來自 commit derived

會變的部分：

• 具體 manifest format（半年一個新 lockfile 格式）
• Artifact registry 主流（OCI / Conda / npm 等都會演化）
• LLM model registry（Hugging Face / Ollama 都會演化）

新 lock 格式 / registry 出來時、回到三分類問：它解的是哪類產物？我能用它 commit manifest 不 commit content 嗎？通常答案 yes。

跟其他章節的關係

• scripts/README.md：本章原理的實作 reference
• Hands-on quickstart：跑通 demo 步驟、為什麼要 rebuild index.pkl
• 4.9 Production resource planning：production runtime 視角、本章是 deployment 視角
• 0.7 隱私資料流原理：什麼可以離開機器、本章是「什麼可以進 git」的 sibling
• 4.22 RAG storage 工程：本章把 embedding index 判為 derived（不進 git、ingest.py 重建）、該章接手 vector index 存進 backend 之後的生命週期管理

從 FTP 拉下來建立 Git repo

用 FTP client 把整個站台完整下載到本地目錄，這份下載就是 production 的快照。下載完成後在該目錄初始化 Git：

1cd /path/to/downloaded-site
2git init

在第一次 commit 之前先處理 .gitignore。PHP 專案需要排除的檔案分三類：套件依賴（由 Composer 或 npm 管理、可重建）、執行期產物（快取、session、上傳檔案）、以及含有機密值的設定檔。

 1# 套件依賴
 2vendor/
 3node_modules/
 4
 5# 執行期產物
 6cache/
 7tmp/
 8sessions/
 9*.log
10
11# 使用者上傳內容（通常很大、且屬於資料不屬於程式碼）
12uploads/
13media/
14wp-content/uploads/
15
16# 機密設定（下一節處理）
17.env
18config.local.php
19wp-config.php

使用者上傳的內容（uploads/、media/）不進 Git 的理由是它屬於資料層：檔案數量可能成千上萬、總容量可能數 GB，Git 不適合管理這類大量二進位檔案。這些檔案的備份策略跟程式碼不同——用 FTP mirror 或 rclone 定期同步到本地即可。

設好 .gitignore 後做第一次 commit：

1git add -A
2git commit -m "production snapshot $(date +%Y-%m-%d)"

這個 commit 就是「接手時 production 長什麼樣」的基準線。後續所有改動都從這裡開始有版本歷史。

Config 分離：讓 Git repo 不含機密值

無 SSH 環境的 PHP 專案常把資料庫密碼、API key、SMTP 憑證直接寫在 config.php 或 wp-config.php 裡。這些檔案如果進了 Git，機密值就跟著 repo 走——推到 GitHub 就等於公開。

分離的模式是把設定拆成兩份：一份進 Git（結構與預設值）、一份不進 Git（實際機密值）。

模式一：.env 檔案

使用 vlucas/phpdotenv 套件或手動解析，讓程式碼從 .env 檔案讀取環境變數：

1// config.php — 進 Git
2$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
3$dotenv->load();
4
5$db_host = $_ENV['DB_HOST'];
6$db_name = $_ENV['DB_NAME'];
7$db_user = $_ENV['DB_USER'];
8$db_pass = $_ENV['DB_PASS'];

1# .env — 不進 Git（.gitignore 已排除）
2DB_HOST=localhost
3DB_NAME=mysite_prod
4DB_USER=mysite_user
5DB_PASS=actual-password-here

同時在 repo 裡放一份 .env.example（進 Git），列出所有需要的環境變數但不填實際值：

1# .env.example — 進 Git，作為範本
2DB_HOST=
3DB_NAME=
4DB_USER=
5DB_PASS=
6SMTP_HOST=
7SMTP_USER=
8SMTP_PASS=

模式二：config.local.php

如果專案不使用 Composer、引入 phpdotenv 成本太高，用 PHP include 分離：

1// config.php — 進 Git
2if (file_exists(__DIR__ . '/config.local.php')) {
3    require __DIR__ . '/config.local.php';
4} else {
5    die('config.local.php not found. Copy config.local.example.php and fill in values.');
6}

1// config.local.php — 不進 Git
2$db_host = 'localhost';
3$db_name = 'mysite_prod';
4$db_user = 'mysite_user';
5$db_pass = 'actual-password-here';

WordPress 的處理

WordPress 的 wp-config.php 同時包含機密值和非機密設定。把整份排除再 include 一份 local 版是最簡單的做法，但也可以只把機密值抽到 .env、wp-config.php 本身保留在 Git 裡：

1// wp-config.php — 進 Git（機密值從 .env 讀）
2$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
3$dotenv->load();
4
5define('DB_NAME', $_ENV['DB_NAME']);
6define('DB_USER', $_ENV['DB_USER']);
7define('DB_PASSWORD', $_ENV['DB_PASSWORD']);
8define('DB_HOST', $_ENV['DB_HOST'] ?? 'localhost');

分離完成後，用 grep 確認 repo 裡沒有殘留的明文密碼：

1git grep -in "password\|passwd\|secret\|api_key\|smtp" -- '*.php' ':!*.example*'

任何命中都要評估：是真的機密值（要移到 .env）還是變數名稱（可以保留）。

FTP 部署的風險控制

FTP 上傳是逐檔覆寫，沒有交易性——上傳到一半斷線、或上傳了有語法錯誤的 PHP 檔案，站台會立刻出問題。風險控制的核心是「每次上傳前知道在改什麼、上傳後知道改了什麼」。

上傳前的比對

FileZilla 的目錄比較功能（「檢視 → 目錄比較 → 啟用」）可以在上傳前看到本地與遠端的差異：哪些檔案是本地較新、哪些是遠端較新、哪些只存在於一邊。上傳前先跑比較、確認差異清單符合預期——如果出現預期外的「遠端較新」檔案，代表有人在伺服器上直接改了東西，要先下載回來合併再上傳。

只上傳改過的檔案

一次上傳整個站台目錄既慢又危險。只上傳 Git diff 顯示的改動檔案：

1# 列出相對於上次部署 tag 改了哪些檔案
2git diff --name-only deploy-2026-06-25 HEAD

把這份清單對照 FileZilla 的比較結果，逐一上傳。量大時用 lftp 的 mirror 指令加 --only-newer flag 只傳新檔。

關鍵檔案的額外保護

index.php、.htaccess、設定檔這類檔案壞掉會讓整個站台無法存取。上傳這些檔案之前，先從伺服器下載一份當前版本存到本地的 _backup/ 目錄（gitignored）。如果上傳後站台出問題，可以立刻把備份版本傳回去。

部署前後的驗證

部署前檢查

部署後驗證

上傳完成後立刻驗證：

1. 首頁能正常載入（HTTP 200、頁面內容正確）
2. 本次改動涉及的功能可正常操作
3. 如果是電商站：結帳流程、金流 callback 測試
4. 檢查 PHP error log（cPanel → 錯誤日誌、或 FTP 下載 error_log 檔案）

如果驗證失敗，回退方式是從 Git 歷史取出上一個版本的受影響檔案重新上傳：

1# 取出上一個部署 tag 的特定檔案
2git show deploy-2026-06-25:path/to/file.php > _rollback/file.php
3# 用 FTP 上傳 _rollback/file.php 覆蓋 prod

CI 化 FTP 部署

手動 FTP 部署的問題是它依賴特定人的 FTP client 和操作紀律。用 GitHub Actions 把 FTP 上傳自動化，可以讓部署變成「push 到 main → CI 跑測試 → CI 上傳到伺服器」的流程，不依賴任何人的本地環境。

 1name: Deploy via FTP
 2on:
 3  push:
 4    branches: [main]
 5
 6jobs:
 7  deploy:
 8    runs-on: ubuntu-latest
 9    steps:
10      - uses: actions/checkout@v4
11        with:
12          fetch-depth: 2
13
14      - name: Deploy to FTP
15        uses: SamKirkland/FTP-Deploy-Action@v4
16        with:
17          server: ${{ secrets.FTP_HOST }}
18          username: ${{ secrets.FTP_USER }}
19          password: ${{ secrets.FTP_PASS }}
20          server-dir: /public_html/
21          exclude: |
22            **/.git*
23            **/.git*/**
24            **/node_modules/**
25            **/.env
26            **/config.local.php

FTP 憑證存在 GitHub repo 的 Secrets 裡（Settings → Secrets and variables → Actions），不寫在 workflow 檔案裡。

CI 化後的改變

限制

FTP 部署沒有原子性（atomic deployment）——檔案逐一上傳的過程中，伺服器上同時存在新舊版本的檔案混合狀態。如果上傳的檔案之間有依賴關係（新的 A.php 引用新的 B.php，但 B.php 還沒上傳完），短暫的錯誤窗口無法避免。流量高的站台如果需要零停機部署，需要升級到 SSH + symlink 切換的部署方式，那屬於 VPS 遷移之後的能力。

Git tagging 部署紀錄

每次部署前在 Git 打一個 tag，讓「這次部署的是哪個版本」有明確的錨點：

1git tag deploy-$(date +%Y-%m-%d-%H%M)
2git push origin --tags

tag 的命名用日期時間戳而非版號，因為這類專案通常沒有語意化版號的概念。tag 的作用是：

• 回退時知道要退到哪個版本（git diff deploy-previous deploy-current 看這次改了什麼）
• 多次部署之間的差異可追蹤
• CI 化後可以用 tag 觸發部署而非每次 push 都部署

資料庫變更的回退跟程式碼獨立處理——程式碼可以靠 Git 回退，資料庫要靠 SQL dump 回退，兩者的回退點要對齊但機制不同。資料庫的備份策略見資料庫備份與變更管理。

跨分類引用

• → 無 SSH 的 FTP / 面板管理環境接管：本篇的母文章，涵蓋接手的完整流程
• → 資料庫備份與變更管理：資料庫端的備份、migration 紀律與回退策略
• → Legacy PHP 的安全盤點：credential 分離之後的存取控制與安全掃描
• → 無 SSH 環境的監控與告警：部署後用外部監控驗證服務正常
• → 模組七：infra 走 PR 流程：從 FTP CI 化進一步演進到完整的 PR review 流程

退出指令（「先還原」「先重來」「先放著」）的執行前要先確認兩件事：還原到哪個狀態、要不要先存 checkpoint。 直接刪掉當前進度、未來想比較沒得比、想恢復也找不到。

為什麼退出指令需要 protocol

商業邏輯

退出指令的字面意思是「拿掉現在做的東西」、但背後通常有更複雜的意圖：

執行者不確認意圖、直接刪 = 把使用者的選項收窄成「沒有了」。事先確認 = 為使用者保留可能性。

這次任務的實際情境

觀察

使用者說：「如果要做到這麼大的複寫原設計、我們先還原回去、先不要做這個變更」。

我立刻刪掉那段 CSS、繼續往下做其他事。沒問「還原到哪」、沒先 commit checkpoint。

判讀

後來想比較「複雜覆寫版本」與「接受原設計版本」的差異 — 沒得比。「複雜覆寫版本」已經不存在於 git 歷史。

正確流程應該是：

1. 收到「還原」指令時、先回應「我會先 commit 當前進度（即使未採用）作為 checkpoint，再還原到 X 狀態。OK 嗎？」
2. 確認後、commit 當前狀態（不 push）、commit message 標明「探索版本、未採用」
3. 還原到 X 狀態
4. 繼續做後續事

未來想比較或恢復、checkpoint 都還在。

執行：退出指令的 protocol

收到退出指令時、依序處理：

Checkpoint 的命名與 commit message

當前進度作為 checkpoint commit、message 應該包含：

1chore(explore): N+1 attempts to remove disclosure marker
2
3探索方向：用 ::-webkit-details-marker / ::marker / display: block 三層
4覆寫移除 disclosure 三角圖示。
5寫了 5 條 CSS 跨 3 種瀏覽器、覆寫成本過高。
6
7最終決定：接受原設計、不採用此方向。
8此 commit 保留探索成果、未來若評估值得做時可參考。

關鍵元素：

• chore(explore): prefix — 標明非正式採用
• 探索方向 — 說明做了什麼
• 最終決定 — 為什麼不採用
• 保留理由 — 未來何時可能重用

未來人看到這個 commit、知道「這是探索、不是當前實作」、不會誤用。

內在屬性比較：四種退出處理

優先選 checkpoint 方式 — 為未來保留比較與恢復的可能性。

退出意圖的辨識

從語氣判斷

不確定就問。「不要這樣寫」這類指令容易被理解成「全還原」、實際只是「這段重寫」。

確認意圖的問法

1你想要：
2  □ 完全還原、刪掉這次的 CSS
3  □ 還原但保留 commit checkpoint、未來可能參考
4  □ 局部修正（哪一段保留、哪一段重寫）
5
6或是其他？

設計取捨：退出指令的處理策略

四種做法、各自機會成本不同。這個專案選 A（Checkpoint + 確認還原範圍）當預設、其他做法在特定情境合理。

A：Commit checkpoint + 確認還原範圍（這個專案的預設）

• 機制：commit 當前進度（標明「探索、未採用」）+ 問「還原到哪個 commit」+ 執行還原
• 選 A 的理由：未來想比較或恢復都還在、checkpoint 成本只是多一個 commit
• 適合：探索性嘗試、未採用方案的退出
• 代價：多一個 commit 在歷史中（可後續 squash 或保留）

B：git stash 暫存

• 機制：把未 commit 的變更存到 stash、不污染 commit 歷史
• 跟 A 的取捨：B 不留 commit、A 留 commit；B 適合「短期暫停、之後恢復」、A 適合「長期探索紀錄」
• B 比 A 好的情境：暫時切到別的工作、之後一定會回來繼續

C：git reset --hard（直接丟）

• 機制：reset 到指定 commit、未 commit 的變更全失去
• 跟 A 的取捨：C 完全清乾淨、A 保留紀錄；C 在 git reflog 內短期還能恢復、但之後永久消失
• C 才合理的情境：確定不要的探索、且確認不需要未來參考

D：直接刪檔案、不留 git 紀錄

• 機制：手動刪 / 改、不 commit
• 成本特別高的原因：未來想比較或恢復都做不到、使用者選項被收窄
• D 是反模式：git 是免費的紀錄工具、不用反而是浪費 — 未來想比較或恢復都做不到、使用者選項被收窄

判讀徵兆

核心原則：退出指令的執行不該收窄使用者的未來選項。Checkpoint = 給未來保留可能性、成本只是多一個 commit。

多人（或多 agent）並行開發時，如果修改集中在同一個檔案，協調成本可能抵消並行的收益。以下是一個具體案例。

v0.3.0 的 JS SDK 開發中，五張 ticket 被並行派發給五個 AI agent：flush 邏輯、離線容錯、自動攔截、頁面生命週期、rate limiting。前四個都需要修改同一個檔案 monitor.ts。

結果：

• 三個 agent 回報 branch protection hook 阻擋 src 編輯
• 兩個 agent 回報 file modified since read 拒絕 Edit（另一個 agent 正在寫同一檔案）
• PM 花了多個回合協調 commit 策略：「你先 commit」「你等他完成」「你只 git add 你的檔案」
• 最終 PM 手動合併所有 agent 的變更，做了一個統一 commit

並行派發的目標是縮短總工時。但五個 agent 改同一檔案時，協調成本抵消了並行的收益。

根因：派發粒度錯在 ticket 層而非檔案層

派發決策看的是 ticket 的獨立性——五張 ticket 描述的功能確實獨立（flush、離線、攔截、生命週期各自有清楚的邊界）。但獨立的功能不等於獨立的檔案。五個功能的修改都集中在 monitor.ts 這一個檔案上。

ticket 獨立 =/= 檔案獨立。並行安全的判斷基準應該是後者。

教訓

派發前掃描 where.files：如果多張 ticket 的目標檔案有交集，序列化派發。前一張完成並 commit 後，再派下一張。

序列的代價比衝突的代價低：五個 agent 序列執行可能需要 5 倍時間，但每個 agent 在乾淨的工作區上操作，不需要協調。五個 agent 並行但衝突，PM 的協調時間加上 agent 的等待和重試，總成本可能更高。

Worktree 隔離不是萬靈丹：git worktree 讓每個 agent 有獨立的工作目錄，避免 working tree 衝突。但如果兩個 agent 修改同一檔案的不同區段，merge 時仍需人工判斷。Worktree 解決的是「同時寫同一個 working tree」的問題，不解決「同時改同一個檔案的語意衝突」。

適用場景

這個 pattern 不限於 AI agent。人類開發者在同一個 Sprint 中被分配修改同一個檔案的不同功能時，也會遇到 merge conflict。差異在於人類可以口頭協調（「我先改完你再改」），agent 目前缺乏這個即時溝通管道。派發者（PM 或 CI 系統）需要在派發時就做好檔案衝突預判。

最基本的線圖能力內建在 git 本身：git log --oneline --decorate --graph 就會用 ASCII 畫出分支線。Oh My Zsh 的 git plugin 把它包成 glog（當前分支）與 gloga（加 --all 看全分支）兩個 alias。這條 alias 是任何環境都成立的底線 — 即使在一台陌生、不能安裝任何東西的機器上，git log --graph 永遠都在。專用工具要解決的，是這條底線之上的兩個缺口：互動瀏覽的流暢度，以及把「看」與「改」整合在同一畫面。

本文承接 終端機圖形化工具總覽 的 TUI 工具脈絡，聚焦 git 線圖這個版控子題（最常被遠端開發者問到）。

三類工具的職責分工

git 線圖工具依承擔的責任分三類，遠端 CLI 情境下各自適用的條件不同。

TUI 互動式瀏覽與操作

TUI 工具負責把 git 歷史開成全螢幕的互動介面，讓游標在 commit、檔案、分支之間移動，並即時在側欄顯示對應的 diff。它跟單純印一次 log 的差別在於「可導航」— 線圖、diff、blame 在同一個畫面裡用鍵盤切換，不必反覆重打指令。

已經在用 tig 的人，可以把後兩者當成「補上操作能力」而非替換：只想瀏覽就停在 tig，要用鍵盤完成 stage/commit/rebase 再加 lazygit，兩者互補。各工具的責任邊界與選型條件在下面逐一展開。

tig 的責任邊界在「看」。它把 git 歷史做成可導航的唯讀視圖，線圖呈現清楚、資源佔用極低，適合只想快速翻歷史與看 diff 的情境。它本身不做版控操作，所以心智負擔小、學習成本低。

lazygit 把責任從「看」擴到「改」。互動式 rebase、cherry-pick、stash 管理、衝突解決、stage 到 commit 的完整流程都能用鍵盤完成，等於把終端機 git 操作整碗端進一個畫面。它的代價是功能多帶來的學習曲線與稍高的資源佔用。

gitui 與 lazygit 定位相近但取捨相反，刻意保持精簡並換取效能。日常的 stage、commit、branch、stash、blame、log 都涵蓋，但進階流程的覆蓋度不追求面面俱到。它跟 lazygit 的深入比較放在後面一節。

純 log 線圖增強（走管線、零 TUI）

這類工具不開全螢幕介面，而是改善 git log 一次性輸出的可讀性，責任是讓線圖更清楚、讓 diff 配色更易讀。它走標準輸出與管線，適合接在腳本裡或當成 alias 隨手用。

git log --graph 系列（也就是 glog / gloga）是這條路線的起點，零安裝、處處可用。git-graph 是專門產生比內建更清楚的 ASCII 分支線的工具，當內建線圖在複雜合併歷史下變得難讀時，它把分支著色與排版做得更工整。delta 是 diff 的語法高亮 pager，嚴格說不算線圖工具，但它把 git log -p 與 git diff 的輸出做成帶配色、帶行號、可左右並排的版面，常跟前述工具搭配使用 — 後面 lazygit 的 side-by-side diff 就是靠它。

這類工具的判讀訊號是：需要的是「印一次看一眼」而非持續導航。它對頻寬特別友善，因為是一次性輸出、不像 TUI 會持續重畫畫面。

桌面 GUI（遠端通常排除）

gitk、git-gui、gitg 這類桌面圖形工具依賴 X11 或桌面環境，在純終端機的遠端連線下無法直接執行，或需要繁瑣且吃頻寬的 X11 forwarding。這個排除有明確前提：本篇限定「只有終端機、不能在遠端裝 IDE agent」的最小情境。若情境允許 IDE 的 remote 機制（VS Code Remote-SSH、JetBrains Gateway）或可接受 X11 forwarding，桌面 GUI 仍能遠端使用、體驗也不差 — 這條前提放寬時，本篇的結論會跟著變。把 GUI 列在這裡只為說明邊界：它們解決的是「有桌面或 IDE 通道」的需求，與「只有終端機」是不同場景。

遠端情境為什麼偏好單一 binary

遠端開發選型有一個容易被忽略的隱性約束：工具的安裝依賴。Go 與 Rust 寫的工具（lazygit、gitui、git-graph、delta）通常編譯成單一 binary，相較需要先裝 runtime 的工具，把檔案搬上去就能用，這是它們在 SSH 情境特別受歡迎的原因之一。

但「單一 binary」要打兩個折扣，照字面 scp 可能撞牆。其一，binary 自身不含 runtime，不代表沒有執行期依賴：lazygit 與 gitui 執行時都會呼叫系統的 git，遠端機沒裝 git 就跑不動。其二，Rust 工具（gitui / delta）預設動態連結 glibc，不是真正的 static；跨發行版或搬進 alpine 容器（用 musl）會出現 GLIBC not found，這種情境要下載對應的 musl 靜態建置版。判讀的分界是：能用系統套件管理器自由安裝時，依語言寫成什麼影響不大；環境受限時，除了「一個檔案」還要確認目標機有 git、且 binary 的 libc 對得上目標系統。這也是為什麼 git log --graph alias 是最後的保命符 — 它連 binary 都不必搬。

lazygit 與 gitui 的定位差異

lazygit 與 gitui 表面功能重疊度很高，選擇依據主要落在以下幾個面向，而非單純「誰比較快」。

技術底色：效能與資源

gitui 用 Rust 做了非同步架構，在 monorepo、歷史很長、或機器資源有限（老舊伺服器、容器內）時反應更跟手，啟動極快、記憶體佔用低。lazygit 的效能日常夠用，但在 diff 或 log 非常大時偶有卡頓、記憶體佔用較高。這是兩者最常被提到的分水嶺，也直接對應遠端機器的強弱。

功能廣度 vs 功能聚焦

這是比效能更根本的定位差異。lazygit 賭功能廣度：互動式 rebase、cherry-pick、stash 管理、衝突解決、自訂指令幾乎都包了，目標是讓人完全不打 git 指令。gitui 賭功能聚焦：涵蓋 stage、commit、branch、stash、blame、log 這些日常約八成的操作，進階流程（複雜 rebase）的覆蓋度刻意保留，設計上傾向不做太重的事。

選型決策邏輯

兩者背後是兩種不同的使用意圖。傾向 lazygit 的，是想用一個工具取代 git CLI、把版控操作整碗端進終端機，願意付稍高的資源代價換廣度與便利。傾向 gitui 的，是想要一個快速的 git 視窗，主要看狀態、看歷史、做基本提交，要求即開即用、進階操作仍回去打 git 指令。一句話收斂：lazygit 押廣度與便利，gitui 押速度與輕量。

生態與社群

lazygit 社群採用度較高、star 數較多、教學與設定檔分享資源豐富，keybinding 與自訂指令的客製空間大。gitui 社群較小但穩定，定位清晰。對需要大量客製或想參考他人設定的情境，lazygit 的生態是實質優勢。長期依賴前也值得瞄一眼維護活躍度（release 節奏決定 bug 修復速度）— 兩者都在活躍維護，但 star 數高不等於修得快，這跟社群熱度是兩件事。

選型判準（遠端 CLI 情境）

把上述收斂成一條判準鏈，對應遠端開發的機器條件：

• 機器資源充足、想要一個工具搞定所有 git 操作：選 lazygit，把它當操作中樞。
• 遠端機器較弱、repo 很大、或只想快速看狀態做提交：選 gitui，換取即開即用與低資源。粗略 tripwire：repo 歷史上萬筆 / monorepo、機器 RAM 約 1GB 以下、或 lazygit 開大 diff 時明顯卡頓，就往 gitui 靠。
• 只需要看歷史與 diff、不在工具裡做版控操作：tig 的唯讀定位最輕量。
• 環境受限、不能安裝：退回 gloga（git log --graph --all），它在任何 git 環境都成立。

這四者能共存。常見的搭配是 tig 看歷史 + lazygit 做操作，兩者互補性高；gitui 與 tig 的瀏覽定位略有重疊，同時留兩個的理由較弱。風險與邊界在於學習成本：操作中樞型工具按一個鍵就改動 repo，初期適合先在拋棄式分支或測試 repo 練手，熟悉後再用到開發分支。

lazygit 上手與 side-by-side diff

lazygit 的介面遵循一個固定心法：左側面板選「對什麼東西操作」、右側看「內容」、底部提示列顯示「當前能按什麼」。底部提示列會隨游標位置動態變化，所以操作不必背全部快捷鍵，迷路時按 ? 會叫出當前面板的上下文敏感說明。

入門只需記幾個導航鍵：Tab 或數字 1~5 切換左側面板（Status / Files / Branches / Commits / Stash），方向鍵或 hjkl 在面板與清單內移動，Esc 返回上一層，q 離開。線圖在 Commits 面板（按 4），全分支關係在 Branches 面板（按 3）。三個最常用的日常操作：在 Files 面板用空白鍵 stage / unstage、stage 完按 c 輸入訊息提交、在 Commits 面板選 commit 後右側自動顯示 diff（Enter 進入檔案層級）。

預設的 diff 是單欄 unified（增刪行逐行上下排列）呈現。要做到像 IDE 那樣左右並排（side-by-side）對齊，lazygit 本身沒有內建這個視圖，需要外接 pager。pager 是負責把長輸出分頁、上色顯示的程式（git 預設用 less）；這裡讓 lazygit 把 diff 文字交給外部 pager 上色並重排成並排版面，最常見的搭配是 delta。安裝 delta 後，在 lazygit 設定檔（~/Library/Application Support/lazygit/config.yml，或 ~/.config/lazygit/config.yml）指定它當 pager 並開啟並排模式：

1git:
2  pagers:
3    - colorArg: always
4      pager: delta --dark --paging=never --side-by-side

--side-by-side 是讓 delta 左右並排的關鍵旗標，--paging=never 讓 delta 只負責上色與排版、捲動分頁仍由 lazygit 處理。git.pagers（list）是現行 lazygit 的設定鍵；舊版的 git.paging.pager（單數）仍可用，新版啟動時會自動 migrate 成上面的形式並改寫設定檔。在窄螢幕（手機、平板遠端）下，並排會把每欄壓得很窄，這種情境改回垂直單欄反而好讀 — side-by-side 的適用條件是螢幕夠寬。

下一步路由

選型確定後，後續深入的方向：

• 想完全用鍵盤取代 git 指令：深入 lazygit 的互動式 rebase、cherry-pick 與自訂指令流程。
• 遠端機器資源吃緊：實測 gitui 在大型 repo 的反應，跟 lazygit 同一個 repo 跑一次比較體感。
• diff 配色與並排需求延伸到日常 git：把 delta 設成 git 全域 pager（git config --global core.pager delta），讓 git diff 與 git log -p 也吃到同一套配色。

git 線圖在整個遠端 CLI 工具選型中的位置，見 終端機圖形化工具總覽 — 本篇屬其中的版控子題、與系統監控的 TUI 工具脈絡相承。

開新功能時，工作目錄常常同時有「改過的舊檔案」和「全新建立的檔案」。 想用 git stash 暫時收起來去拉主線變更，卻發現新檔案沒被收進去， 還散在工作目錄裡，導致 rebase / 切分支時出狀況。

原因是預設的 git stash 不會收 untracked 檔案。

-u 是什麼

-u 是 --include-untracked 的縮寫，u 就是 untracked（未追蹤檔案）。

Git 把工作目錄的檔案分成幾種狀態，跟 stash 有關的是這三種：

「untracked」就是 git status 裡出現在 Untracked files: 區塊的新檔案。

Git 預設不收 untracked，是因為這類檔案常是編譯產物、log、暫存檔，全收進 stash 反而把雜物一起搬動；要求用 -u 明確表態，是把「要不要連新檔一起暫存」的決定權留給操作者。-a（--all）範圍更大，連 .gitignore 忽略的也一起收，日常少用。

正確流程（拉主線變更）

1git stash push -u -m "暫存"    # -u 連 untracked 新檔案一起收
2git pull --rebase origin main  # 或 git fetch + git rebase
3git stash pop                  # 把修改倒回工作目錄

替代做法

也可以「先 commit 再 rebase，事後再 git reset --mixed HEAD~1 把 commit 拆回未提交狀態」。 這個做法會把 untracked 新檔一起收進 commit，省去記得加 -u 的步驟，適合改動較大、想先有一個完整快照的情況。

兩者取捨：commit 法會在分支歷史暫時多一顆 commit，rebase 完要記得 reset 拆回；stash 法把改動收在 refs/stash、不進分支 log，但 untracked 檔要記得 -u。日常小改動用 stash 心智負擔較低，改動大或想保留完整快照時用 commit 法。

核心命題：source code doc 寫給「未來的讀者」，commit message 寫給「想了解過去發生什麼的考古者」。兩者是不同文件，內容該分開。 設計原則：時序敏感的資訊（為什麼這次改動、考慮過什麼方案）放 commit；持續適用的資訊（當前契約、不變量）放 source。

本篇是 函式文件分層設計 反模式 3「過去式 doc」的展開——把「source 跟 commit message 的時序職責邊界」拉成獨立主題討論。

起點：兩份文件的職責容易被混在一起

Source code doc 的職責是「描述當前 code 的契約跟行為」、commit message 的職責是「描述某次改動做了什麼跟為什麼做」——兩者讀者不同、時序屬性不同、本該各歸各家。實務上這兩份文件的職責經常被混在 source code doc 一處：source 變成所有歷史的垃圾桶、commit message 反而沒人認真寫。

實務上常看到的污染：

1/// 修了 issue #123 的 race condition
2/// 從 v2.3 開始改用 lock-free 結構
3/// TODO: @alice 之後可能要改用 SkipList
4void process() { ... }

這段 doc 混了三類資訊：

1. 過去發生什麼（修了 issue #123）→ 屬於 commit message
2. 過去做過什麼決定（v2.3 開始改用 lock-free）→ 屬於 commit message / changelog
3. 未來可能要改什麼（TODO @alice 改用 SkipList）→ 屬於 issue tracker / TODO 系統

沒有一條是「未來讀者讀這份 code 需要的資訊」——三條都凍結在過去某一刻、source 卻被當成歷史快照在用。要釐清這個問題、得先想清楚兩種文件各自的讀者與時間性。

時序差異：當前狀態 vs 狀態轉移

關鍵差別是時間性：

• Source code doc 描述「現在這份 code 在做什麼」——只要 code 不變，doc 就持續有效
• Commit message 描述「那一刻為什麼要改 code」——commit 完成的那一秒就成為歷史

把過去式的內容塞進 source code doc，會讓 doc 變成「凍結在某個歷史時點的快照」，而不是描述當前狀態。

該寫在 commit message 的內容

Commit message 的核心職責是回答「這次改動做了什麼、為什麼做」——所有「凍結在某次提交時點」的資訊都應該住在這裡、而不是被塞進 source 變成過時快照。下面四類是最常被誤放進 source 的內容：

1. 改動的動機（為什麼這次要動）

1fix: prevent double-charge on payment retry
2
3Payment gateway 對同一個 transaction_id 會回傳 200 但實際扣款兩次
4（incident #4521）。在 client 端加上 idempotency_key，gateway
5看到重複的 key 直接回 cached response。

「為什麼動」幾乎永遠屬於 commit message。source code 只需要描述「現在的行為是什麼」，不需要解釋「過去為什麼變成這樣」——除非那個「為什麼」對未來呼叫者仍是必須知道的限制（見後面段落）。

2. 評估過的替代方案（why not X）

1refactor: replace stream with reactive value
2
3考慮過三個方案：
4- A. 改成 broadcast stream：最 minimal，但保留同樣的 payload 語義模糊問題
5- B. 加新 broadcast stream 平行存在：兩條 stream 容易不同步
6- C. 拆成 reactive value（採用）：與系統其他 service 一致、消除多訂閱問題
7
8選 C 因為與 codebase 其他 service 風格對齊，雖然改動範圍最大。

「考慮過 A、B、C，選了 C」這類資訊對 reviewer 重要，對未來讀 code 的人多半不重要——他們看到的是 C 的結果，不關心你考慮過 A、B。這類資訊屬於 commit message / PR description，不屬於 source code doc。

3. Migration / 部署相關步驟

1feat: migrate user_profile from int_id to uuid
2
3注意：
4- 跑 migration 0042 之前先確認所有 client 已升到 v3.2 以上
5- migration 預估 2 小時（10M rows），建議週末執行
6- rollback：reverse migration 0042 然後 redeploy v3.1

部署時序與步驟是當下發布動作的一部分，commit / release notes 該寫；source code 不該背這個負擔。

4. Bug 號、ticket 連結、incident 紀錄

1fix: handle empty cart in checkout button visibility
2
3Closes #1234
4Related: incident-2026-04-12 (button stuck enabled)

把 ticket 號 / issue 連結寫在 commit message，git blame 出來的 commit 直接帶你去原始討論。寫在 source code 反而會 outdated（issue 關了、tracker 換了、URL 改了）。

該寫在 source code doc 的內容

Source code doc 的核心職責是描述「當前 code 的契約跟行為」——只要 code 不變、doc 就持續有效。下面四類是「持續適用」的資訊類別、屬於 source 的家：

1. 當前對外契約

1/// 從本地購物車移除指定商品
2///
3/// 找不到對應品項時不做事；不會拋例外。
4void removeFromLocalCart(CartItem item);

這是「現在這個 function 對 caller 承諾什麼」——持續適用，跟「上週為什麼加這個 function」無關。

2. 隱性需求 / 必要的呼叫順序

1/// 必須在 [init] 之後呼叫；否則 throw `StateError`。
2void process() { ... }

「呼叫順序」是當前 code 的契約限制，未來呼叫者必須遵守。屬於 source code doc。

3. 對未來讀者仍然重要的「過去原因」

少數情況下，「為什麼以前這樣決定」對未來讀者仍是必要資訊——典型是「這個寫法看起來怪，但有非顯然的原因」：

1void processPayment(Payment p) {
2  // 刻意不 retry —— payment gateway 是非冪等，retry 會造成重複扣款
3  // （見 incident-2026-04-12）。失敗一律拋給上層人工處理。
4  return _gateway.charge(p);
5}

這條註解兼具「歷史原因」和「持續適用的限制」——未來維護者看到這段 code 會想「為什麼沒 retry？」，這條註解防止他「順手加上」。這類兼具兩種性質的內容是少數該留在 source 的歷史相關 doc。

判斷標準：「未來讀者不知道這條歷史會做錯決定嗎？」

• 是 → 留 source
• 不是 → 留 commit

4. 不變量 / invariant

1class CircularBuffer {
2  /// 元素數量永遠在 [0, capacity] 之間
3  int get length => ...;
4}

不變量是「這個型別永遠成立的事實」，是契約的一部分，屬於 source。

反模式

反模式 1：把 commit message 內容塞進 source

正向概念：source code doc 描述「現在的行為」、git log 才是「歷史演進」的家。兩者各自有對應的工具（IDE 看 doc、git log 看演進）、各司其職就能讓兩邊都精準。

 1// 反：寫成歷史紀錄
 2/// 2024-01-15 加上 retry 邏輯
 3/// 2024-03-22 改用 exponential backoff
 4/// 2024-07-08 加上 jitter 避免 thundering herd
 5Future<Response> fetch(String url) { ... }
 6
 7// 正：source 只寫當前行為
 8/// 自動 retry 失敗的請求，使用 exponential backoff + jitter
 9Future<Response> fetch(String url) { ... }
10// 演進歷史在 git log 看

把所有歷史塞進 source 等於在 source code 重做一份 git log——但 git log 已經存在、且結構化、可搜尋、有 author / timestamp。重做一份在 source 只會 outdated（下次再加邏輯時忘了補日期就破功）、而 git log 永遠是同步的。

反模式 2：commit message 只寫 “update” / “fix”

正向概念：commit message 是給未來考古者的線索——git blame 跳到一個 commit 時、message 是讀者拿到的第一份資訊。寫得清楚、考古路徑就短；寫得模糊、考古者得繼續挖 PR / 找原作者問。

1- update
2- fix
3- wip
4- final
5- final v2
6- final v2 真的

這類 commit message 當下就沒人看得懂、半年後 git blame 把人帶到 message 寫 “update” 的 commit、等於把讀者帶到死巷。合理 commit message 的最小單位是 <type>: <one-line summary>、例如 fix: handle empty cart in checkout——一行就好、但要說清楚做了什麼。

反模式 3：source code doc 寫滿 TODO / FIXME

正向概念：「想未來改但還沒改」屬於 issue tracker——issue tracker 有優先序、有 owner、有 due date、能被排程。source code 的 TODO 沒有這些屬性、會被慢慢遺忘。

1/// TODO: refactor to use streams
2/// FIXME: handle null case
3/// HACK: temporary workaround for issue #234
4/// XXX: this is broken under high load
5void doSomething() { ... }

這些都是「想未來改但還沒改」的事——把它們留在 source 有三個問題：

• TODO 在 source 不會被 prioritize（產品 / 專案管理工具看不到 source 內的 TODO）
• FIXME 在 source 容易被忽略（讀的人會想「不是我寫的不是我的問題」）
• HACK / XXX 警告只在第一次讀時有效、第二次讀的人會麻木

問題嚴重需要立刻處理 → 開 ticket、commit fix；不嚴重可以等 → 開 backlog ticket、source 別寫。把待辦項從 source 搬到 issue tracker、會被真正當成「待辦」處理。

反模式 4：把 PR description 抄一份進 source

正向概念：PR description 是「這次提交的時空快照」、source code doc 是「持續適用的當前契約」。兩者描述的是同一段 code 在不同時序下的不同切面、各自有對應的家。

1/// 這個 function 是為了支援新的 multi-currency 結帳流程。
2/// 詳細需求見 PR #4521 與設計文件 https://wiki.../...
3/// 業務需求：客戶可以混合多幣別商品結帳，結帳當下統一換算成 settlement currency。
4/// QA 已驗證 5 種主要幣別組合 + 邊界 case。
5void multiCurrencyCheckout() { ... }

PR description 該寫的內容（業務脈絡、設計連結、QA 範圍）抄進 source、會讓 source 凍結在「這次新增時的時空狀態」——半年後 PR 已經是歷史、連結可能失效、QA 範圍可能擴展、但 source 還停在那一刻。PR description 留在 PR、source 只寫 function 當前的對外契約。

Git blame archaeology workflow

當 source code doc 跟 commit message 各司其職時，考古工作流會變得清晰：

 1讀者看到一段 code 不懂為什麼這樣寫
 2  ↓
 3先看 source code doc
 4  ↓
 5不夠 → 跑 git blame
 6  ↓
 7找到引入這段 code 的 commit
 8  ↓
 9讀 commit message
10  ↓
11不夠 → 點進去看完整 PR / issue

這個工作流要能順利跑，前提是：

1. commit 顆粒度合理——一個 commit 一個邏輯改動，不要「fix typo + refactor + add feature」混在一起，否則 blame 出來看到一個改 50 個檔案的 commit，message 寫 “stuff”，等於沒線索
2. commit message 寫清楚動機——不是「changed X」（git diff 看得出來），而是「changed X because Y」
3. 重大決定用 PR 描述補充——commit message 太長不適合塞長文，PR description 是放長文的地方

如果這三點做到，未來讀 code 的人有一條清楚的考古路徑，不必逼 source code doc 背所有歷史。

一個分配工具

決定一條資訊放哪時，問三個問題：

1. 「未來讀者不知道這條會做錯決定嗎？」
   • 是 → source code doc
   • 不是 → commit message
2. 「這條描述的是當前的行為，還是某次轉移？」
   • 當前行為 → source code doc
   • 某次轉移 → commit message
3. 「Code 改了，這條會不會 outdated？」
   • 不會（描述當前狀態）→ source code doc
   • 會（描述特定時間點）→ commit message

三個問題收斂到同一個直覺：「凍結在過去」屬於 commit、「持續適用」屬於 source。

邊界：什麼時候 source 還是該帶歷史脈絡

「歷史進 commit、契約進 source」是預設、但有些情境 source 還是該保留歷史脈絡——共通特徵是「未來讀者不知道這段歷史會做錯決定」：

• 看似怪、但有非顯然原因的寫法：「刻意不 retry、payment gateway 是非冪等」——下個維護者順手加 retry 會出事
• 跟非預期外部行為對齊的 workaround：「拆兩步 query 避開 SQLite 32-bit Android 的 integer overflow（issue #1234）」——讀者重構時會想「為什麼不一次查」
• 保留某段 code 的合規 / 法務原因：「依 GDPR 留 30 天可恢復、不是直接刪」——縮短到 7 天會違反法規
• 效能調優的非顯然參數：「batch size = 32 是 production 跑出來的甜蜜點、改大會 OOM」——下次 review 看到「為什麼不開大」時得知道過去的實驗結果

判斷標準：「未來讀者不知道這條歷史就會做錯決定嗎？」答「是」就留在 source、答「不是」就留在 commit。

一句話 heuristic

把整個討論濃縮：

Source code doc 寫給「正要動這段 code 的人」、commit message 寫給「想知道為什麼當初這樣寫的人」。

寫東西之前先問：我寫這段，是要幫正要動 code 的人做對決定，還是要幫回顧歷史的人理解某次改動？兩個讀者要找的資訊不同，分成兩處寫，雙方都受惠。

收束：兩份文件協同，源頭就要分清楚

很多團隊抱怨「source code doc 太亂、commit message 沒人寫」，本質是這兩份文件的職責沒分清楚。Source 想包辦所有事就會充滿過時內容；commit message 沒人寫是因為「反正歷史會寫進 source」變成預設。

把兩者的職責分清楚，兩份文件都會變健康：

• source 變短、變精準：只寫當前契約，doc 不會 outdated
• commit message 被認真寫：因為它是某些資訊的唯一家
• 考古路徑清楚：blame → commit → PR 是可預期的回溯路徑

寫 doc / 寫 commit 是同一個技能的兩面。不要把任何一邊當成另一邊的替代品。

開發到一半，發現 commit log 裡「實作功能」這個 commit 不只改了功能檔案，還包含了「定義 model」階段的檔案變更。這些變更在開發節奏上應該屬於前面的 commit，但實際上被混在後面的 commit 裡。想把這部分檔案的變更從後面那個 commit 抽出來，合併到前面的 commit 裡，其他檔案保持原狀。

範例

gitGraph
   commit id: "A (model 定義)"
   commit id: "B (其他)"
   commit id: "C (功能實作)"
   commit id: "D (其他)"

四個 commit 的角色：

• A（接收目標）：commit C 中對 models/foo.dart 的修訂應該屬於這裡
• B（中間插入）：A 跟 C 之間有別的 commit，不能簡單 squash
• C（變更來源）：同時改了 models/foo.dart 和其他 6 個檔案
• 限制：只想搬走 models/foo.dart，其他檔案保持原狀

解法核心

這個方法的核心靠 3-way merge 自動跳過重複變更 — 不需要手動從 C 移除檔案變更，git 會自己偵測「這個變更已在新 base」自動處理。

具體利用兩個 git 機制：

1. git rebase -i 搭配 edit：在指定 commit 暫停，讓我們手動修改該 commit 的內容
2. 3-way merge 自動 dedup：當後續 commit 被 replay 時，git 比較三個版本（base / theirs / mine），發現該檔案變更已在 mine 裡，就自動跳過

為什麼是這個方法

其他可能方案的成本：

• git cherry-pick 後手動解衝突：cherry-pick 會把整個 commit（包含所有檔案）複製到 A 後面，然後再手動移除不需要的變更。多出一個 commit，且流程較長
• 用 git format-patch 提取單一檔案：format-patch 提取的是整個 commit 的 patch，無法只選擇某個檔案。需要手動編輯 patch 檔，失敗風險高
• 直接 git add -p 重新 commit：需要回到 A 後重新手動 commit 一遍，工作量大且容易遺漏

這個方法的優勢：自動化程度最高 — 只需在 A 和 C 時暫停，git 會在 replay C 時自動判斷哪些變更要跳過，無需手動識別衝突或編輯 patch。

步驟

1. 建立備份 tag

歷史改寫前先綁 tag，這樣如果出現預期外的結果可以快速復原。

1git tag backup-before-rebase HEAD

2. 進入 interactive rebase，把 A 跟 C 都標成 edit

從 A 的父 commit 開始 rebase，並把 A 跟 C 都標為 edit：

1# 用環境變數注入「自動把 pick 改成 edit」的 sequence editor
2GIT_SEQUENCE_EDITOR='sed -i.bak \
3  -e "s/^pick \(<A短hash>\)/edit \1/" \
4  -e "s/^pick \(<C短hash>\)/edit \1/"' \
5GIT_EDITOR=true \
6git rebase -i <A短hash>^

macOS 的 sed -i 需要加空字串引數（-i ''）或像上面用 -i.bak 留 backup 檔。 Linux 的 sed -i 不需要。 如果更放心用編輯器手動操作，可以拿掉 GIT_EDITOR=true，讓 rebase 開你慣用的編輯器手動把兩行的 pick 改成 edit。

執行後 git 會在 A 暫停。

3. 在 A：把 C 中該檔案的版本拉進來，amend

1# 把 C 那個 commit 對該檔案的最終內容 checkout 到工作區
2git checkout <C短hash> -- path/to/file.dart
3
4# 加入並 amend 到 A
5git add path/to/file.dart
6git commit --amend --no-edit
7
8# 繼續
9git rebase --continue

git checkout <commit> -- <path> 會把指定 commit 的該檔案版本放進工作區。 因為 A 是 C 的祖先，C 的版本就是「A 的版本 + C 的 diff」，等於把 C 對該檔案的變更搬到 A。

4. 在 C：確認 git 自動跳過該檔案的變更

rebase 繼續後會 replay B、然後在 C 暫停（因為我們也把它標成 edit）。 此時該檔案對 C 的變更應該已被 git 自動跳過，驗證一下：

1git show HEAD --stat
2git diff HEAD~ HEAD -- path/to/file.dart

第一個指令的檔案清單不應該再出現 path/to/file.dart，第二個指令應該是空輸出。

驗證無誤後，git 已自動完成跳過，直接繼續：

1git rebase --continue

3-way merge 為什麼會自動跳過？ Replay C 時 git 用 3-way merge：

• base（C 的原始父 commit）：該檔案沒變
• theirs（C 原始版本）：該檔案有 X 變更
• mine（amend 後的 A 接續而來的目前 HEAD）：該檔案已經有 X 變更

mine 跟 theirs 的最終狀態一致 → git 認定變更已套用，replay 後的 C 對該檔案就是 no-op。

5. 驗證最終樹狀態跟備份一致

最關鍵的 sanity check：內容不應該變，只是 commit 邊界移動。

1git diff backup-before-rebase HEAD

輸出必須是空的。非空就代表有東西被吃掉或多出來，立刻回滾：

1git reset --hard backup-before-rebase

確認沒問題後刪 tag：

1git tag -d backup-before-rebase

完整指令摘要

 1# 0. 備份
 2git tag backup-before-rebase HEAD
 3
 4# 1. Rebase，把 A 與 C 都標 edit
 5GIT_SEQUENCE_EDITOR='sed -i.bak \
 6  -e "s/^pick \(<A短hash>\)/edit \1/" \
 7  -e "s/^pick \(<C短hash>\)/edit \1/"' \
 8GIT_EDITOR=true \
 9git rebase -i <A短hash>^
10
11# 2. 在 A：拉檔案、amend、繼續
12git checkout <C短hash> -- path/to/file.dart
13git add path/to/file.dart
14git commit --amend --no-edit
15git rebase --continue
16
17# 3. 在 C：驗證、繼續（不需要動手）
18git show HEAD --stat
19git rebase --continue
20
21# 4. 驗證樹一致
22git diff backup-before-rebase HEAD   # 應為空
23
24# 5. 清理
25git tag -d backup-before-rebase

衍伸：當變更區段在 A 跟 C 重疊

如果 A 跟 C 對該檔案動的是同一個區段（不是這個範例的 non-overlapping）， 3-way merge 會跳出衝突，需要手動編輯。流程：

flowchart LR
   A["在 A amend 完"] --> B["replay 到 C 衝突"]
   B --> C["手動編輯衝突檔"]
   C --> D["git add + git rebase --continue"]

   style B fill:#e53e3e,color:#fff,stroke:#c53030
   style C fill:#dd6b20,color:#fff,stroke:#c05621

衝突解決原則：保留 A 已經帶過去的版本（也就是 C 想再套一次但其實一樣的內容）， 讓 C 對該檔案的這次 replay 變成 no-op。

注意事項

• 改寫已 push 的歷史需要 force push：用 git push --force-with-lease 比 --force 安全， 別人有新 commit 推上去時會被擋住，避免覆寫
• 沒 push 的 commit 改起來無風險：怎麼操作都只影響本地
• 改寫 main / master 是禁忌，這個技術只適用於 feature branch
• codegen 檔案：如果 .freezed.dart / .g.dart 等是被 gitignore 的，重組 source commit 後本地需要重跑 build_runner。如果 codegen 也在版控，建議連同 source 一起搬，否則 source 跟 codegen 對不齊
• Sequence editor 自動腳本搞不定的話，拿掉 GIT_EDITOR=true，讓 rebase 開你慣用的編輯器手動改 pick → edit，更直觀
• 驗證樹一致性是這個工作流程的安全網。每次重組完一定要 git diff backup HEAD 跑一次

適用：

• 客製需求要對抗多層（vendor CSS、framework reconciliation、browser default、UA stylesheet）
• 收到「先還原」「先重來」「換個方向」「我們重新開始」這類指令

不適用：純 greenfield 開發（沒有舊代碼要對抗、沒有探索成果要保留）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋成本告知模板、checkpoint 命名慣例、reset 前的確認協議。

何時參閱本文件

為什麼成本要攤開、為什麼 revert 要 checkpoint

成本攤開的價值

當客製要對抗多層、執行者沉默地堆疊 !important + specificity hack + polyfill — 結果使用者：

1. 看到「能用」的成果、以為成本低
2. 升級 vendor / 換 browser 後壞掉、驚訝於維護負擔
3. 不知道有沒有更便宜的替代方案（換 vendor、放棄該客製、改設計）

把成本攤開 = 使用者在執行前就決定值不值、不在事後後悔。

Revert 含 checkpoint 的價值

探索的成果即使沒採用、仍然是「為什麼不採用」的證據。直接清空：

1. 下次遇到類似需求、可能再走一遍同樣的死路
2. 失去 A 跟 B 兩條路的對比基礎
3. 部分技術選擇（命名、結構）可能仍有用、被連帶丟掉

Checkpoint 把「探索」與「採用」分開記錄、保留比較與恢復的可能。

成本告知協議

步驟 1：列出對抗的層

寫第一條規則前、列出將打到哪幾層：

步驟 2：估規則數量與風險

 1這個客製需要打到：
 2- Vendor CSS（pagefind 主題色）：寫 3-4 條規則覆蓋預設色
 3- Framework reconciliation（drawer 內容會被重渲染）：把客製 UI 放邊界外
 4- 升級風險：pagefind 升級 minor 版本、選擇器改名 → 客製樣式失效
 5
 6建議方案：
 7A. 完整客製（如上）— 工時 1 hr、升級時要重檢
 8B. 只改 CSS variable（如果 vendor 提供）— 工時 5 min、升級安全
 9C. 放棄客製、用 vendor 預設 — 工時 0、視覺差異使用者要接受
10
11推薦 B（如果 vendor 有提供 var）、否則 A。哪一個？

步驟 3：使用者選擇後再開始

不管選 A / B / C、選擇本身已經被攤開。使用者後續看到維護負擔、不會驚訝。

Revert / Checkpoint 協議

步驟 1：確認還原目標

使用者說「先還原」時、回問：

1「還原」是指：
2
3(a) 丟掉所有未 commit 的修改、回到 HEAD
4(b) 回到某個特定 commit（哪一個？）
5(c) 部分還原（哪些檔案 / 哪些功能）
6(d) 換思路、但保留結構（命名、檔案組織保留、實作換掉）
7
8我建議先做 commit 把當前進度保存、再 reset — 您是哪一種？

步驟 2：commit 當前進度當 checkpoint

不管是哪種還原、先 commit：

1git add -A
2git commit -m "checkpoint: explored [方向 X], not adopted
3
4- 嘗試了 [做法 A]、結果 [現象]
5- 假設 [Z] 驗證後不成立
6- 保留供未來對比、不採用為最終解
7"

Checkpoint commit 的特徵：

• 主題明確含「checkpoint」「explored」「not adopted」字樣
• body 寫「為什麼不採用」、不只寫「做了什麼」
• 在後續 main branch 上不會被 merge 進去（用 branch 隔離或日後 rebase 丟）

步驟 3：執行 reset

確認 checkpoint commit 完成後、執行使用者要的還原：

1# 視類型而定
2git reset --hard <target>      # 完全還原
3git checkout <commit> -- <file> # 部分還原
4git revert <commit>             # 保留歷史的還原

危險動作（git reset --hard、git checkout .、git clean -fd）執行前再次跟使用者確認 — 即使有 checkpoint commit、也要避免把 checkpoint 自己 reset 掉。

Wrong vs Right 對照

範例 1：覆寫成本

使用者：「pagefind 搜尋框的顏色改成我們的品牌色」

錯（直接做、沒攤成本）：

1.pagefind-ui__form { background: var(--brand) !important; }
2.pagefind-ui__search-input { background: var(--brand) !important; color: white !important; }
3.pagefind-ui__button { background: var(--brand-dark) !important; }
4/* ... 8 條 !important 後、終於看起來對 */

兩週後 pagefind 升級、class 名稱改了一個 — 全壞。使用者驚訝。

對（先報成本）：

1顏色客製有兩條路：
2
3A. Pagefind 提供的 CSS variables（看了 docs：--pagefind-ui-primary、--pagefind-ui-text 等）
4   → 改 4 個 var、升級安全、5 min
5
6B. 直接覆寫 class 規則（要 8 條 !important）
7   → 升級可能壞、需要追蹤 vendor changelog、1 hr
8
9推薦 A、除非您要的視覺超出 var 能控制的範圍。哪個？

範例 2：「先還原」處理

使用者：「等等先還原、這個方向不對」

錯：

1git checkout .  # 直接清空、丟掉 30 分鐘探索成果
2# 之後想對比「為什麼方向 A 不行」時、什麼都沒留下

對：

1我把當前進度先 commit 成 checkpoint、再還原 — 還原的目標是：
2
3(a) 回到開始這個方向之前的 commit（HEAD~3）
4(b) 回到 main 最新
5(c) 換個 branch、保留這個 branch 供以後參考
6
7通常 (c) 最安全、(a) 最常見。您要哪個？

確認後：

1git add -A
2git commit -m "checkpoint: explored grid-row layout, not adopted (drawer is form's child, grid invalid)"
3git reset --hard HEAD~4  # 或使用者指定的 target

Checkpoint commit 的命名慣例

checkpoint: 是本文件主推 — 比 wip: 多了「不採用」的明確標記、未來 grep git log --grep=checkpoint 能快速找到「曾經試過但放棄的方向」。

自檢清單（dogfooding）

收到客製需求或 revert 指令時：

• 寫第一條覆寫規則前、有沒有列出「對抗哪幾層、規則數量、升級風險」？
• 有沒有給使用者 ≥ 2 個選項（含「不做」或「降級客製」）？
• revert 前有沒有確認還原目標的精確意圖？
• revert 前有沒有 commit 一個 checkpoint？
• checkpoint 的 commit message 有沒有寫「為什麼不採用」、不只寫「做了什麼」？

成本沒攤、checkpoint 沒 commit → 退回去補。

延伸閱讀

對應的事後檢討（在 content/report/）：

• override-depth-cost-report — 覆寫深度的成本告知
• revert-instruction-handling — 「先還原」「先重來」類退出指令的處理

Last Updated: 2026-04-26 Version: 0.1.0

使用 git commit --fixup + git rebase --autosquash 修改歷史 commit 後， 修改內容被後續的 commit 覆蓋，導致變更未生效。

範例

gitGraph
   commit id: "A (refactor)" type: HIGHLIGHT
   commit id: "B (fix)"
   commit id: "C (fix)"
   commit id: "D (feat)" type: REVERSE

HIGHLIGHT = 要修改的目標 commit（A） REVERSE = 意外包含同一檔案變更的 commit（D）

• 目標：透過 fixup 修改 commit A，移除 table_service.dart 中的 try-catch
• 問題：commit D 在開發時意外 stage 了 table_service.dart 的變更，導致 rebase 後 commit D 重新套用了舊的內容，覆蓋了 commit A 的修改

解決方案：從 commit 中移除不該包含的檔案

前置確認

先確認哪些 commit 修改了目標檔案：

1git log --oneline -- lib/data/services/table/table_service.dart

輸出類似：

1de60cc9 feat: 追加多語系           ← 不該包含此檔案
2b55e504 refactor: 各 Service 實作   ← 預期的修改

確認 commit D 確實不該包含該檔案後，進行修復。

步驟

1. 暫存目前的工作變更（如果有的話）

1git stash

2. 啟動 interactive rebase，將目標 commit 標記為 edit

1GIT_SEQUENCE_EDITOR="sed -i '' '1s/^pick/edit/'" git rebase -i <目標commit>~1

說明：

• <目標commit>~1 表示從目標 commit 的前一個 commit 開始 rebase
• GIT_SEQUENCE_EDITOR="sed -i '' '1s/^pick/edit/'" 自動將第一行（目標 commit）從 pick 改為 edit，避免手動編輯
• macOS 的 sed -i 需要 '' 參數，Linux 則不需要

以本例來說：

1GIT_SEQUENCE_EDITOR="sed -i '' '1s/^pick/edit/'" git rebase -i de60cc9~1

執行後 Git 會停在 de60cc9，等待你修改。

此時的 commit 狀態：

gitGraph
   commit id: "A (refactor)"
   commit id: "B (fix)"
   commit id: "C (fix)"
   commit id: "D (feat)" type: REVERSE tag: "HEAD (edit)"

3. 將目標檔案還原到「前一個 commit」的狀態

1git checkout HEAD~1 -- <檔案路徑>

以本例來說：

1git checkout HEAD~1 -- lib/data/services/table/table_service.dart

說明：

• HEAD~1 是目標 commit 的前一個 commit
• 這會把檔案還原到 commit D 之前的狀態，等於「撤銷 commit D 對這個檔案的修改」
• 還原後檔案會自動被加入暫存區（staged）

此時可以用 git status 確認狀態，應該會看到：

1interactive rebase in progress; onto <hash>
2  ...
3Changes to be committed:
4  (use "git restore --staged <file>..." to unstage)
5        modified:   lib/data/services/table/table_service.dart

4. 修改 commit 並繼續 rebase

1git commit --amend --no-edit && git rebase --continue

說明：

• --amend 修改當前 commit（即 de60cc9）
• --no-edit 保留原本的 commit message 不變
• git rebase --continue 繼續處理後續的 commit

完成後的 commit 狀態：

gitGraph
   commit id: "A (refactor)" type: HIGHLIGHT
   commit id: "B (fix)"
   commit id: "C (fix)"
   commit id: "D' (feat)" tag: "HEAD"

D 變為 D’（新的 hash），不再包含 table_service.dart 的變更。

5. 恢復暫存的工作變更（如果有的話）

1git stash pop

驗證

確認目標 commit 不再包含該檔案的修改：

1git show <新的commit hash> --stat

輸出的修改清單中不應出現 table_service.dart。

完整指令摘要

 1# 0. 暫存工作區
 2git stash
 3
 4# 1. 進入 interactive rebase，自動標記目標 commit 為 edit
 5GIT_SEQUENCE_EDITOR="sed -i '' '1s/^pick/edit/'" git rebase -i <目標commit>~1
 6
 7# 2. 還原該檔案到 commit 之前的狀態
 8git checkout HEAD~1 -- <檔案路徑>
 9
10# 3. 修改 commit 並繼續 rebase
11git commit --amend --no-edit && git rebase --continue
12
13# 4. 恢復工作區
14git stash pop
15
16# 5. 驗證
17git show HEAD --stat

衍伸：搭配 fixup 的完整工作流程

當你需要修改歷史 commit A 的內容，但後面的 commit D 又意外包含同一個檔案的修改時：

正確操作順序

flowchart LR
   Step1["① 清理 commit D\n移除不該包含的檔案"] --> Step2["② 修改 commit A\nfixup + autosquash"]

   style Step1 fill:#e53e3e,color:#fff,stroke:#c53030
   style Step2 fill:#38a169,color:#fff,stroke:#2f855a

如果先做 fixup 再處理 commit D，fixup 的修改會被 commit D 覆蓋。 所以一定要先清理後面的 commit，再修改前面的 commit。

fixup + autosquash 參考指令

1# 建立 fixup commit（指向要修改的目標 commit）
2git add <修改的檔案>
3git commit --fixup=<目標commit hash>
4
5# 執行 autosquash rebase（自動合併 fixup commit）
6GIT_SEQUENCE_EDITOR=true git rebase -i --autosquash <目標commit>~1

說明：

• --fixup=<hash> 會建立一個以 fixup! 為前綴的 commit
• --autosquash 會自動將 fixup commit 排到目標 commit 後面並標記為 fixup
• GIT_SEQUENCE_EDITOR=true 跳過編輯器，直接執行（因為 autosquash 已經排好了）

注意事項

• 這些操作會改寫 git 歷史，只適用於尚未 push 到遠端的 commit（或你有權 force push 的分支）
• 操作前建議用 git log --oneline -10 確認目前的 commit 順序
• 如果 rebase 過程中遇到衝突，用 git status 查看衝突檔案，手動解決後執行 git add + git rebase --continue
• 如果想放棄 rebase，可以用 git rebase --abort 回到操作前的狀態

目錄

• 安裝
• 基本概念
• 常用操作
  • 移除檔案或資料夾
  • 只保留特定路徑
  • 重新命名檔案或資料夾
  • 修改 commit 訊息
  • 修改作者資訊
• 進階操作
• 注意事項
• 常見問題

安裝

macOS

1# 使用 Homebrew
2brew install git-filter-repo
3
4# 或使用 pip
5pip3 install git-filter-repo

Linux

1# Ubuntu/Debian
2sudo apt install git-filter-repo
3
4# 或使用 pip
5pip3 install git-filter-repo

Windows

1# 使用 pip
2pip install git-filter-repo

基本概念

什麼時候使用 git filter-repo？

• 從歷史記錄中移除敏感資訊（密碼、API 金鑰等）
• 移除不小心 commit 的大型檔案
• 將子目錄拆分成獨立的 repository
• 合併多個 repository
• 批量修改 commit 作者資訊

重要提醒

注意：git filter-repo 會重寫 Git 歷史，這意味著：

1. 所有 commit hash 都會改變
2. 需要 force push 到遠端
3. 其他協作者需要重新 clone 或 reset

常用操作

移除檔案或資料夾

移除單一檔案

1git filter-repo --invert-paths --path path/to/file.txt --force

移除資料夾

1git filter-repo --invert-paths --path path/to/folder --force

移除多個路徑

1git filter-repo --invert-paths --path .env --path secrets/ --path config/credentials.json --force

使用 glob 模式移除

1# 移除所有 .log 檔案
2git filter-repo --invert-paths --path-glob '*.log' --force
3
4# 移除所有 node_modules 資料夾
5git filter-repo --invert-paths --path-glob '**/node_modules/*' --force

使用正規表達式移除

1# 移除所有 .env 開頭的檔案
2git filter-repo --invert-paths --path-regex '^\.env.*' --force

只保留特定路徑

將 repository 縮減為只包含特定資料夾（適用於拆分專案）：

1# 只保留 src 資料夾
2git filter-repo --path src --force
3
4# 保留多個路徑
5git filter-repo --path src --path docs --path README.md --force

重新命名檔案或資料夾

1# 將 old-name 重新命名為 new-name
2git filter-repo --path-rename old-name:new-name --force
3
4# 將資料夾移動到子目錄
5git filter-repo --path-rename src:app/src --force
6
7# 將所有檔案移到子目錄
8git filter-repo --to-subdirectory-filter my-subdir --force

修改 commit 訊息

建立一個 Python 腳本 message-callback.py：

1# message-callback.py
2import re
3
4def message_callback(message):
5    # 將 "bug" 替換為 "fix"
6    return re.sub(b'bug', b'fix', message)

執行：

1git filter-repo --message-callback '
2    return message.replace(b"bug", b"fix")
3' --force

或使用外部檔案：

1git filter-repo --message-callback "$(cat message-callback.py)" --force

修改作者資訊

使用 mailmap 檔案

建立 .mailmap 檔案：

1New Name <new@email.com> Old Name <old@email.com>

執行：

1git filter-repo --mailmap .mailmap --force

使用 callback 函數

1git filter-repo --name-callback '
2    return name.replace(b"OldName", b"NewName")
3' --email-callback '
4    return email.replace(b"old@email.com", b"new@email.com")
5' --force

進階操作

移除大型檔案

找出大型檔案：

1git filter-repo --analyze
2cat .git/filter-repo/analysis/blob-shas-and-paths.txt | head -20

移除超過特定大小的檔案：

1git filter-repo --strip-blobs-bigger-than 10M --force

替換敏感內容

建立替換規則檔案 replacements.txt：

1regex:password=.*==>password=REDACTED
2literal:my-secret-api-key==>API_KEY_REMOVED

執行：

1git filter-repo --replace-text replacements.txt --force

只處理部分歷史

1# 只處理最近的 commit
2git filter-repo --refs HEAD~10..HEAD --path sensitive-file --invert-paths --force
3
4# 處理特定分支
5git filter-repo --refs main --path old-folder --invert-paths --force

保留備份

1# 在操作前建立備份分支
2git branch backup-before-filter
3
4# 或 clone 一份完整備份
5git clone --mirror original-repo backup-repo

注意事項

操作前檢查清單

• 確保工作目錄是乾淨的（git status 無未 commit 的變更）
• 建立備份（branch 或完整 clone）
• 確認沒有其他人正在使用這個 repository
• 了解 force push 的影響

Remote 會被移除

git filter-repo 執行後會自動移除 origin remote。執行時你會看到以下提示：

1NOTICE: Removing 'origin' remote; see 'Why is my origin removed?'
2        in the manual if you want to push back there.

為什麼要移除 Remote？

這是 git filter-repo 的安全機制設計，目的是保護你和你的團隊：

1. 防止意外推送：重寫歷史後，所有 commit hash 都會改變。如果你不小心直接執行 git push，會把重寫後的歷史推送到遠端，可能覆蓋其他人的工作，造成嚴重問題。

2. 強迫你停下來思考：移除 remote 後，你必須：

   • 確認是否真的要推送重寫後的歷史
   • 手動重新加入 remote
   • 明確使用 --force 參數推送

3. 給你機會通知團隊：在重新加入 remote 和 force push 之前，你有機會先通知其他協作者，讓他們做好準備。

如何處理

執行完 git filter-repo 後，依序執行：

1# 1. 重新加入 remote
2git remote add origin <repository-url>
3
4# 2. 確認 remote 已加入
5git remote -v
6
7# 3. Force push（確認團隊已知情後再執行）
8git push origin --force --all

Force Push

重寫歷史後需要 force push：

1# Push 所有分支
2git push origin --force --all
3
4# Push 所有 tags
5git push origin --force --tags

通知協作者

其他協作者需要執行以下操作來同步：

1# 方法一：重新 clone（推薦）
2git clone <repository-url>
3
4# 方法二：強制重設（注意：會丟失本地未 push 的變更）
5git fetch --all
6git reset --hard origin/<branch-name>

常見問題

Q: 執行時出現 “Refusing to run without fresh clone” 錯誤

這是安全機制，使用 --force 參數來覆蓋：

1git filter-repo --invert-paths --path file.txt --force

Q: 如何還原操作？

如果有備份分支：

1git checkout backup-before-filter
2git branch -D main
3git checkout -b main

如果有備份 repository：

1git remote add backup /path/to/backup-repo
2git fetch backup
3git reset --hard backup/main

Q: 為什麼我的 repository 大小沒有變小？

執行以下命令來清理：

1git reflog expire --expire=now --all
2git gc --prune=now --aggressive

Q: 可以只影響特定分支嗎？

可以，使用 --refs 參數：

1git filter-repo --invert-paths --path file.txt --refs main --force

Q: 如何預覽變更而不實際執行？

使用 --dry-run 參數：

1git filter-repo --invert-paths --path file.txt --dry-run

參考資源

• 官方文件
• 官方手冊
• 常見使用案例