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 的核心規則只有一條：package 目錄內的路徑結構，就是安裝後相對於目標目錄的路徑結構。

1~/dotfiles/zsh/.zshrc          → ~/.zshrc
2~/dotfiles/nvim/.config/nvim/  → ~/.config/nvim/
3~/dotfiles/git/.gitconfig      → ~/.gitconfig

每個頂層目錄（zsh/、nvim/、git/）是一個 stow package，可以獨立安裝或移除。

常用指令

 1cd ~/dotfiles
 2
 3# 安裝：在目標目錄（預設 $HOME 的上一層，通常用 --target）建立 symlink
 4stow zsh                # 安裝 zsh package
 5stow zsh git nvim tmux  # 批次安裝多個 package
 6stow */                 # 安裝所有 package
 7
 8# 移除：刪除該 package 建立的 symlink
 9stow -D nvim
10
11# 重新安裝（移除 + 安裝）
12stow -R zsh
13
14# 收養：如果目標位置已有檔案，--adopt 把它移進 repo 再建 symlink
15stow --adopt zsh

--adopt 是首次把現有配置納入 dotfile 管理時的關鍵操作——它把家目錄的既有檔案「收養」進 repo（移動過去），然後建 symlink。之後 git diff 就能看到 repo 版本跟原版的差異。

Folding 與 Unfolding

Stow 會自動判斷要 symlink 整個目錄還是逐一 symlink 檔案：

• Folding：目標目錄不存在、或目錄內所有檔案都由同一個 package 管理 → symlink 整個目錄
• Unfolding：目標目錄已有其他來源的檔案 → 展開成逐檔 symlink，保留既有檔案不受影響

這個機制讓多個 package 可以共存於同一個目標目錄（如 ~/.config/）。

限制

• 只管 symlink 映射，不管套件安裝（套件由 Brewfile 或 packages.txt 處理）
• 不管 file permission——需要 0600 的 secret 檔靠 symlink 繼承來源權限，無法在部署時自動 chmod
• 沒有 template 機制——同一份配置在不同機器要不同內容時，需要在配置檔內用 shell 的 OS 判斷處理

完整選型比較見管理策略與選型。

本文的做法基於 GNU Stow——將 dotfile repo 的檔案透過 symlink 對應到家目錄的工具（完整說明見管理策略與選型）。一個 repo 跨平台的做法是三層分離，每層處理不同粒度的差異：

第一層：stow 選擇性安裝

Stow 的 package 機制天然支持跨平台。repo 裡同時放 macOS 和 Linux 的配置，安裝時只 stow 該 OS 需要的 package：

1# macOS
2stow zsh git zellij btop broot
3
4# Linux desktop
5stow zsh git zellij btop broot hyprland waybar wofi mako

hyprland、waybar 這些目錄放在 repo 裡但 macOS 不 stow，不會有副作用。bootstrap script 裡用 uname 自動決定要 stow 哪些 package：

1PACKAGES=(zsh git zellij btop broot)
2
3if [[ "$(uname -s)" == "Linux" ]]; then
4    for pkg in hyprland waybar wofi mako hyprlock; do
5        [[ -d "$pkg" ]] && PACKAGES+=("$pkg")
6    done
7fi

第二層：配置檔內的 OS 分流

同一份配置檔裡，用 uname 區分 macOS 和 Linux 的差異。適合處理 PATH、工具初始化路徑這類「同一個用途、不同 OS 路徑」的狀況：

 1# path.zsh
 2typeset -U PATH
 3export PATH="$HOME/.local/bin:$PATH"    # 共用
 4
 5if [[ "$(uname)" == "Darwin" ]]; then
 6    # Homebrew Ruby、FVM、Android SDK（macOS 路徑）
 7    [[ -d "/opt/homebrew/opt/ruby/bin" ]] && export PATH="/opt/homebrew/opt/ruby/bin:$PATH"
 8    export PATH="$HOME/fvm/default/bin:$PATH"
 9    export PATH="$PATH:$HOME/Library/Android/sdk/emulator"
10fi
11
12if [[ "$(uname)" == "Linux" ]]; then
13    # Android SDK（Linux 路徑）
14    [[ -d "$HOME/Android/Sdk/emulator" ]] && export PATH="$PATH:$HOME/Android/Sdk/emulator"
15fi

1# tools.zsh — autojump 的 source 路徑在兩個 OS 不同
2if [[ "$(uname)" == "Darwin" ]]; then
3    [ -f /opt/homebrew/etc/profile.d/autojump.sh ] && . /opt/homebrew/etc/profile.d/autojump.sh
4else
5    [ -f /usr/share/autojump/autojump.sh ] && . /usr/share/autojump/autojump.sh
6fi

每個路徑加 [[ -d ]] 或 [ -f ] 存在性檢查——即使在正確的 OS 上，如果該工具沒裝也不會報錯。

第三層：local.zsh 放機器專屬設定

不是「macOS 的設定」而是「這台特定機器的設定」——工作專案 alias、公司 VPN proxy、只有這台機器需要的 PATH——放在 ~/.config/zsh/local.zsh，不進 Git。

1# .zshrc 裡的載入方式
2[[ -f "$HOME/.config/zsh/local.zsh" ]] && source "$HOME/.config/zsh/local.zsh"

1# ~/.config/zsh/local.zsh（不在 repo 裡，每台機器自己建）
2alias unimall-dev='cd ~/project/unimall_shop && ./scripts/run_commands.sh dev'
3alias unipos-dev='cd ~/project/unipos && ./scripts/run_commands.sh dev'

Repo 裡放一份 local.zsh.example 作為範本，.gitignore 裡排除 local.zsh 本身。

套件清單也分 OS

1~/dotfiles/
2├── Brewfile              # macOS: brew bundle dump 產生
3├── packages-arch.txt     # Arch Linux: pacman -Qqe > packages-arch.txt
4└── ...

Bootstrap script 依 OS 讀對應的清單安裝套件。

Stow 跨平台的邊界

這個三層模型適合「配置檔本身大部分通用、差異只在 PATH 和少數工具路徑」的狀況——也就是多數開發者的實際情境。判斷是否需要遷移到 chezmoi 的訊號：

• 同一份配置檔裡超過一半的行數是 OS 分流 → chezmoi template 更乾淨
• 需要在配置檔裡注入 secret（API key、token） → chezmoi 的 secret 管理是必要功能
• 管理的機器超過三種 OS/角色組合 → template 的條件判斷比 shell if-else 更可維護

多數情況下 stow + uname + local.zsh 就足夠。

目錄結構設計

以 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 一個。