from Pixabayfrom Pixabay

兩年多前，我寫了這篇〈是時候同步你的 dotfiles 了——我選擇 yadm〉，當時的主要動機是想要在多個 Linux VM 之間同步設定檔。

該文章介紹了「何謂 dotfiles」（後端工程師應該都很熟悉），以及我認為的「dotfiles 同步工具」的兩大流派：

  1. Symbolic Link。
  2. Bare Git。

然而，兩年之間，我幾乎很少在文中提起它。

事實上，我這段期間使用的 yadm 的頻率確實不高！

但這並不代表我沒有同步 dotfiles 的需求，只是真正的核心需求在於跨平台，尤其是 macOS 與 Linux 之間。

若僅是在不同 Linux VM 之間同步，就顯得有點小打小鬧，實用性不足。

我日常開發主要都在 Mac 上，而 Mac 與 Linux 的設定落差雖不大，但絕不會完全相同——這讓單一套設定難以通用。

比如我的 Mac 上有一些 Homebrew 的環境變數，在 Linux 上無用武之地不說，還可能造成執行錯誤。

總之，若不解決跨平台問題，那 yadm 的價值將發揮不到一半。

上個月我終於鐵了心，把這件事搞定了！

做完只覺得，我實在太晚開始，跨平台同步的價值非常巨大且實用。

因此，儘管使用這類工具的人並不多，我也要寫下這篇文章，供有志之士參考！

本文主旨與目標讀者

本文重點在於介紹 yadm 的跨平台設定檔、關聯機制，還有基本操作。

所以我會假設你已經用過了 yadm——其實沒用過也無妨，因為常見的操作並不複雜。你可以等看了效果後再決定是否學習 yadm。

目標讀者

不可否認，本文的目標讀者是軟體工程師，尤其是後端開發者。

非技術出身的讀者，可能連 dotfiles 的作用都不容易理解——這很正常。

總之，對於一個熱衷於「客製化工具設定」的開發者，我相信 dotfiles 的同步是肯定要學的。

太實用了！

Alternate Files 介紹

yadm 最強大的能力之一，就是透過「Alternate Files」（下稱 alt files）來實現跨平台同步，它能依據作業系統、主機名稱等條件，自動尋找對應的設定檔。

這是實現跨平台 dotfiles 管理的核心關鍵。

實際範例：我的 dotfiles 結構

這是我的 dotfiles repo 現況，我們只要關注這些「檔名」即可：

1
2
3
4
5
6
7
8
9
10
11
.
├── .aliases##default
├── .aliases##os.Darwin
├── .aliases##os.Linux
├── .p10k.zsh##os.Darwin
├── .p10k.zsh##os.Linux
├── .zprofile##default
├── .zprofile##os.Darwin
├── .zshrc##default
├── .zshrc##os.Darwin
└── .zshrc##os.Linux

可以大概看出，我僅僅同步了 4 個主要設定檔，雖然加上 alt files 後，實際上總共有 10 個檔案。

這個命名結構反映出兩種主要形式——共用檔與變體檔：

  • ##default：所有平台共通的預設設定（共用檔）
  • ##os.Darwin/os.Darwin：依作業系統不同而變化的設定（變體檔）

這種設計的重點是「分層與組合」。

yadm 在處理 alt files 時，會優先使用符合條件的變體（如 Darwin），若該變體不存在，則退回（fallback）至 default 檔案。

如此一來，我們就能針對特定平台進行客製設定，同時保有共用邏輯。

yadm Alt Files 的三大重點

我知道，光這樣講並不容易理解。

簡單來說，我覺得這些 alt files 有三個學習重點。

一、「後綴」命名格式與樣式

在特殊標記##之後的「os 層級」命名格式是固定的！

換言之，os.Darwin、os.Darwin這些「後綴」名稱不可自訂，千萬不要打錯了。

事實上這類後綴可以有非常多樣的寫法，有些確實需要自定義，比如文件中的：

1
2
3
4
$HOME/path/example.txt##class.Work
$HOME/path/example.txt##class.Work,~os.Darwin
$HOME/path/example.txt##os.Darwin,hostname.host1
$HOME/path/example.txt##os.Darwin,hostname.host2

這允許你即使在同一種平台，也能讓不同主機，甚至不同使用者之間產生一定的差異與客製。

不過我覺得，區分 macOS 和 Linux 就已經非常實用。

我建議你也這樣做就好，因為我認為 yadm 已然不算很平易近人的工具XD，如果還要了解這些複雜的後綴規則與用法，恐怕讓人退避三舍。

二、路徑的尋找規則

在相同前綴不同後綴的一系列的檔名中，yadm 只會依照「尋找規則」，選取其中一個建立 Symbolic Link，讓它指向系統真正會讀取的檔案。

1
2
3
├── .zshrc##default
├── .zshrc##os.Darwin
└── .zshrc##os.Linux

以.zshrc為例，在 macOS 上，它會找到.zshrc##os.Darwin。

而在 Linux 上則是.zshrc##os.Linux。

透過這套尋找規則，yadm 就能在不同作業系統提供設定檔的差異化。

三、共用檔的角色

承上，熟悉 dotfiles 的你應該不難猜到，.zshrc##default要放的內容，就是兩邊都會「共用」的部分。

然後，在「變體」檔的開頭，要去source共用檔的內容！

以我的.zshrc##os.Darwin為例，開頭內容如下：

1
2
3
4
5
6
7
8
# macOS 專屬 zsh 設定

# 先載入共用設定
source "$HOME/.zshrc##default"

# Homebrew node@18 路徑（macOS 專屬）
export PATH="/opt/homebrew/opt/node@18/bin:$PATH"
...

如果沒有共用檔，自然就不需要開頭的source。

像p10k.zsh因為設定複雜，我直接區分兩種版本，根本沒有共用部分：

1
2
├── .p10k.zsh##os.Darwin
├── .p10k.zsh##os.Linux

當你完成上述的檔案設計並同步 dotfiles 後，只需執行以下指令：

1
yadm alt

yadm 會尋找並關聯該主機上對應的檔案。

注意，這個步驟必不可少！不然你會發現，雖然所有 dotfiles 都已同步到本機，但這些檔案並沒有被實際使用。

而所謂的「關聯」，如前所述，就是建立 Symbolic Link。

在 Mac 上執行結果如下：

1
2
3
4
5
❯ yadm alt
Linking /Users/kyo/.aliases##os.Darwin to /Users/kyo/.aliases
Linking /Users/kyo/.p10k.zsh##os.Darwin to /Users/kyo/.p10k.zsh
Linking /Users/kyo/.zprofile##os.Darwin to /Users/kyo/.zprofile
Linking /Users/kyo/.zshrc##os.Darwin to /Users/kyo/.zshrc

而 Linux 則是：

1
2
3
4
5
❯ yadm alt
Linking /home/kyo/.aliases##os.Linux to /home/kyo/.aliases
Linking /home/kyo/.p10k.zsh##os.Linux to /home/kyo/.p10k.zsh
Linking /home/kyo/.zprofile##default to /home/kyo/.zprofile
Linking /home/kyo/.zshrc##os.Linux to /home/kyo/.zshrc

Beautiful！

yadm 使用忠告

yadm 是 Git 的 wrapper，操作它等於在操作一個裸露的 Git repo——而且這個 repo 還是你的 Home 目錄😱

這意味著，yadm 的操作會直接影響到你的系統設定檔。

如果你太隨意下達像是yadm reset、yadm add .等指令，有可能會讓你的系統檔案直接損毀XD

我就曾因為情急不慎操作，導致某台 VM 的設定變得半殘XD，只能砍掉重練。

安全使用法則

因此，我歸納了一個更安全的使用之道：

  • 所有設定修改，都集中在本機上的 dotfiles repo 中，透過 VS Code 進行編輯。
  • 其他機器（包括本機）僅透過yadm pull同步修改後的結果，不進行任何yadm commit、yadm push等動作。

這樣的模式確保你的設定變動只從單一來源發出，降低毀損風險，也讓同步過程更安全可控。

此外，如果我要做yadm pull、yadm list、yadm status三個指令（後兩者並不會改變檔案狀態，所以是安全的）以外的操作，我一定會先問 AI！

因為這工具看似簡單，但威力絕不容小覷。

結語：同步 dotfiles 真的非常愉快

不誇張，自從設好跨平台同步後，開發幸福感大幅提升！

我以前太小看 yadm 了，可以跨平台之後，我變得更常改動 dotfiles、加入新的 alias，絲毫不用擔心同步問題。

我知道這篇文章不會有太多受眾，怕哪是軟體工程師，也不是人人都熱衷此道。

但如果你想在多台 Mac 和多台 Linux VM（我目前有 3 台 Mac 與兩台 Linux VM）同步設定檔，卻仍在猶豫要選用哪一款工具的話。

不用想了，就選 yadm 吧！