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 管理

多台機器共用 dotfile repo 時，需要一套同步策略來處理「改了配置後怎麼讓其他機器也更新」。

Git push/pull（手動）

最基本的做法：改了就 commit + push，另一台機器 pull + 重新 apply。優點是簡單、沒有額外依賴。缺點是容易忘記——在公司機器上改了一個 alias，回家忘記 push，隔天公司又改了一版，兩邊 diverge。

適合只有一兩台機器、改動不頻繁的人。

自動同步

chezmoi 內建 chezmoi update 指令（pull + apply 一步完成），搭配 cron 或 systemd timer 定期執行：

 1# ~/.config/systemd/user/chezmoi-update.timer
 2[Unit]
 3Description=Update dotfiles daily
 4
 5[Timer]
 6OnCalendar=daily
 7Persistent=true
 8
 9[Install]
10WantedBy=timers.target

1# ~/.config/systemd/user/chezmoi-update.service
2[Unit]
3Description=chezmoi update
4
5[Service]
6Type=oneshot
7ExecStart=/usr/bin/chezmoi update --no-tty

自動同步減少手動操作，但要注意衝突處理——如果兩台機器同時改了同一個檔案且都 push，後面那台的自動 pull 會遇到 merge conflict。實務上 dotfile 很少有真正的衝突（兩台機器同時改同一行的機率低），但偶爾發生時需要手動介入。

機器差異的處理

推薦的模式是 main branch 放所有共用配置，機器差異用條件判斷處理。

用 shell 的 OS 判斷：

1# ~/.zshrc
2if [[ "$(uname -s)" == "Darwin" ]]; then
3    export PATH="/opt/homebrew/bin:$PATH"
4    alias ls="ls -G"
5else
6    alias ls="ls --color=auto"
7fi

用 chezmoi template（Go template 語法）：

1# chezmoi 管理的 .zshrc.tmpl
2{{ if eq .chezmoi.os "darwin" -}}
3export PATH="/opt/homebrew/bin:$PATH"
4{{ end -}}
5
6{{ if eq .chezmoi.hostname "work-laptop" -}}
7export HTTP_PROXY="http://proxy.corp:8080"
8{{ end -}}

chezmoi template 的優勢是條件判斷發生在 apply 階段，產出的檔案裡看不到 template 語法，乾淨且不依賴 shell 的 runtime 判斷。

不推薦每台機器一個 branch 的做法。短期可行，長期一定 diverge——main 加了新配置，各 branch 要 rebase 或 merge，忘了就漂移。一份 main + template 條件判斷是長期可維護的結構。

Secret 排除與管理

dotfile repo 通常是 public 或至少多人可見的。以下東西進了 repo 等於把鑰匙掛在門口：

• SSH 私鑰（~/.ssh/id_*、*.pem）
• API token、password、.env 檔案
• GPG 私鑰
• cloud provider 的 credential 檔案（~/.aws/credentials、~/.config/gcloud/application_default_credentials.json）
• browser profile 裡的 cookie / session

.gitignore 是第一道防線

# SSH 私鑰
*.pem
id_*
known_hosts
authorized_keys

# 環境變數
.env
.env.*

# Cloud credentials
credentials
application_default_credentials.json

但 .gitignore 只防「不小心 add」，不防「故意 add -f」。更重要的是建立習慣：repo 裡永遠只放「看到了也沒關係」的東西。

SSH config 的特殊處理

~/.ssh/config（host alias、ProxyJump 設定、port forwarding）本身不含 secret，可以進 repo——它記錄的是「連線要怎麼走」而不是「憑證是什麼」。但同一個 ~/.ssh/ 目錄下的私鑰絕對排除。

stow 管理時的目錄結構範例：

1dotfiles/
2└── ssh/
3    └── .ssh/
4        └── config        # 進 repo
5        # id_rsa 不放這裡
6        # known_hosts 不放這裡

三個層級的 secret 管理

層級一：手動。.gitignore 排除 secret 檔案，在 README 記錄「這些東西需要在新機器手動設定」。最低成本、對只有一兩台機器的人足夠。

層級二：密碼管理器整合。chezmoi 支援從 1Password、Bitwarden、pass（Unix password manager）等拉取 secret：

1# chezmoi template 語法
2{{ (onepasswordRead "op://Personal/SSH Key/private key").value }}

配置檔的 template 裡引用密碼管理器的條目，apply 時自動填入。secret 不在 repo 裡，但 repo 知道去哪拉。

層級三：加密存放。用 age 或 sops 把 secret 加密後直接存在 repo 裡。解密需要對應的 key。chezmoi 原生支援 age 加密：

1# 加密一個檔案
2chezmoi add --encrypt ~/.ssh/id_rsa
3
4# repo 裡看到的是加密後的內容
5cat ~/.local/share/chezmoi/private_dot_ssh/id_rsa.age

加密存放的好處是 secret 跟著 repo 走、不用另外設密碼管理器。風險是加密 key 本身變成唯一的依賴——丟了 key，加密的 secret 就拿不回來。

層級選擇取決於安全需求和便利需求的平衡。多數情況從層級一開始，覺得手動處理太煩再往上升級。

環境重建的實際流程

假設拿到一台全新的 Arch Linux 機器，要從零重建完整的 Hyprland 桌面環境。以下是 end-to-end 的步驟，對應 bootstrap script 的每個階段。

階段一：最小可用環境

1# Arch 安裝完成後，base system 只有 bash 和基本工具
2sudo pacman -S git base-devel

這是 bootstrap script 的唯一外部前提：有 Git 能 clone repo、有 base-devel 能編譯 AUR 套件。其他一切由 script 處理。

階段二：取得 dotfile repo

1git clone https://github.com/you/dotfiles ~/dotfiles
2cd ~/dotfiles

如果 repo 是 private，這一步需要先設定 SSH key 或用 HTTPS + token。這是前面提到的 secret 雞生蛋問題——clone 含有 SSH config 的 repo 本身就需要 SSH key。解法通常是：第一次用 HTTPS clone，deploy 完 SSH config 後把 remote 改成 SSH。

階段三：執行 bootstrap

1./scripts/install.sh

script 依序：安裝套件（Hyprland、waybar、rofi、wezterm、zsh、neovim、stow 等）、用 stow 部署配置到 $HOME、執行初始化（換 shell、安裝 neovim plugin）。

階段四：手動處理

bootstrap 處理不了（或不該處理）的部分：

• SSH 私鑰：從備份或密碼管理器取回，放到 ~/.ssh/，設定正確權限（chmod 600）
• Git 簽署用的 GPG key：如果有用 commit signing
• 密碼管理器登入：如果 secret 管理用了層級二或三

階段五：硬體相關調整

Hyprland 的 monitor 設定（解析度、縮放、排列位置）跟實際接的螢幕有關，這部分配置每台機器都不同：

1# ~/.config/hypr/hyprland.conf 的 monitor 段
2# 這幾行在每台機器上都要調
3monitor=DP-1, 2560x1440@144, 0x0, 1
4monitor=HDMI-A-1, 1920x1080@60, 2560x0, 1

處理方式有兩種：把 monitor 設定拆成獨立的 monitor.conf，主配置用 source 引入，monitor.conf 不進 repo（加進 .gitignore）、每台機器本地維護；或者用 chezmoi template 按 hostname 判斷。

顯卡驅動（Intel/AMD 通常自動、NVIDIA 需要額外安裝 nvidia-dkms 和設定環境變數）也是硬體相關的步驟，可以放在 bootstrap script 的 OS 判斷裡，但通常 Arch 安裝階段就已經處理。

階段六：驗證

1# 登出 TTY，重新用 Hyprland 登入
2# 或者直接在 TTY 執行
3Hyprland

登入後確認：視窗管理器正常運作、keybind 正確、狀態列出現、字型正確渲染、終端機配色正常。如果某個元件沒反應，通常是套件沒裝或配置路徑不對——回去檢查 bootstrap 的套件清單和 stow 的 symlink。

時間預估

整個流程在網路順暢的情況下，大約 30 分鐘到 1 小時，取決於套件數量和下載速度。主要時間花在套件安裝（pacman 下載 + 編譯 AUR 套件）。配置 deploy 本身是秒級操作（stow 只建 symlink）。

對比沒有 dotfile 管理時的重建：邊想邊裝、裝了忘記某個工具的名稱、配置靠記憶手打、兩天後還在調某個快捷鍵為什麼不對。差距在「可預期 vs 碰運氣」。

維護節奏

環境重建能力需要持續維護，不是設定完就一勞永逸。

日常習慣：新裝一個工具時，順手更新套件清單（brew bundle dump 或手動加一行到 packages.txt）。改了一個配置後，commit + push。這個習慣的建立成本低，但需要刻意練幾週才會變成反射動作。

定期檢查：每隔幾個月在 VM 或 container 裡跑一次完整的 bootstrap，驗證 script 還能從零跑通。配置會演進、套件會改名或被取代、script 裡硬寫的路徑可能失效——定期驗證才能確保「這份重建指令真的能重建」，而不是一份過期的紀錄。