dotfiles 管理 — chezmoi vs yadm vs raw シンボリックリンク、Mac 編

新しい Mac を入手するたびに .zshrc、.gitconfig、~/.config/... をコピー&ペーストしているなら、dotfiles 管理ツールが必要だ。一度セットアップすれば、新しいマシンで 1 コマンドで完全な設定を復元できる。dotfiles 管理の本質はファイルの同期ではなく、環境の意図を保存することにあると考える — 何を設定し、なぜそうしたかを記録することで、次のマシンで同じ判断を繰り返さなくて済むからだ。

このガイドでは 3 つのアプローチ（chezmoi・yadm・raw シンボリックリンク＋Git）を比較し、推奨する chezmoi のセットアップを詳しく説明する。

TL;DR

1. dotfiles ツールが必要な理由

.zshrc を直接 Git リポジトリに置いてシンボリックリンクするのは動くにはは動く。しかし次のような問題が積み重なる：

• マシン別の差異: 仕事用 Mac の git user.email と個人用を分けると、分岐がハードコードになりがち。
• シークレット: API キー / SSH 設定が混在すると危険で、.gitignore を忘れやすい。
• 双方向性: ~/.zshrc を直接編集するとリポジトリとずれ、どちらが正しいかわからなくなる。
• 新しいマシン: clone → 依存関係インストール → シンボリックリンク → パーミッション設定…毎回。

dotfiles ツールはこれを一貫したワークフローにまとめる。

2. 選択肢の比較

chezmoi

Go ベースの CLI。テンプレートエンジン（マシン別分岐）、シークレット（1Password / Bitwarden 連携）、双方向性（chezmoi diff / chezmoi apply）。

yadm

~ の dotfiles を直接 Git リポジトリとして扱う Git ラッパー。学習コストゼロ。マシン別分岐はサポートされているが制限がある（.zshrc##os.Darwin のような alt ファイル）。

raw シンボリックリンク＋Git

~/dotfiles/ にファイルを置いてインストールスクリプトでシンボリックリンクを張る。最も透明性が高いが、すべての機能を自分で実装する必要がある。

推奨: chezmoi

1〜3 台のマシンを持つ個人には、chezmoi が圧倒的に使いやすい。1 時間の学習投資が長期にわたって回収できる。

3. chezmoi のセットアップ

3.1 インストール

brew install chezmoi

3.2 GitHub リポジトリを準備する

GitHub に private の dotfiles リポジトリを作成（名前は任意）。空で構わない。

3.3 chezmoi を初期化する

chezmoi init github.com/yourname/dotfiles
# または SSH が使える場合:
chezmoi init git@github.com:yourname/dotfiles.git

~/.local/share/chezmoi/ がワーキングツリー（実際の Git リポジトリ）になる。

3.4 ファイルを追加する

# .zshrc を chezmoi 管理下に置く
chezmoi add ~/.zshrc
 
# または複数まとめて
chezmoi add ~/.gitconfig ~/.tmux.conf ~/.config/starship.toml

ファイルは ~/.local/share/chezmoi/dot_zshrc としてコピーされる（先頭のドットが dot_ プレフィックスに変換される）。

3.5 コミット＋プッシュ

chezmoi cd          # ワーキングツリーに移動
git add .
git commit -m "init dotfiles"
git push -u origin main
exit                # 元の場所に戻る

3.6 新しいマシンで復元する

# 新しい Mac で
brew install chezmoi
chezmoi init --apply github.com/yourname/dotfiles

以上で完了。すべての dotfiles が ~ に展開されて即座に適用される。

4. マシン別分岐（テンプレート）

chezmoi の最も強力な機能。同じ .gitconfig が仕事用と個人用で自動的に切り替わる：

~/.local/share/chezmoi/dot_gitconfig.tmpl

内容：

[user]
    name = Your Name
{{- if eq .chezmoi.hostname "Work-MacBook" }}
    email = me@company.com
    signingkey = AAAA....
{{- else }}
    email = personal@example.com
{{- end }}
 
[core]
    editor = nvim
    autocrlf = input

.tmpl 拡張子でテンプレートとしてマークされる。適用時に chezmoi がホスト名で分岐する。

4.1 利用可能な変数

chezmoi data       # すべてのコンテキスト変数を表示

よく使う変数：

• .chezmoi.os — darwin / linux / windows
• .chezmoi.hostname — マシン名
• .chezmoi.arch — arm64 / amd64
• カスタム変数 — chezmoi edit-config で追加

4.2 OS 別ファイル

dot_zshrc を dot_zshrc.tmpl にリネームして OS で分岐：

{{ if eq .chezmoi.os "darwin" -}}
# macOS のみ
export HOMEBREW_PREFIX="/opt/homebrew"
eval "$($HOMEBREW_PREFIX/bin/brew shellenv)"
{{ else if eq .chezmoi.os "linux" -}}
# Linux のみ
export PATH="$HOME/.linuxbrew/bin:$PATH"
{{ end -}}
 
# 共通
alias ll='ls -lah'

5. シークレット連携

dotfiles に API キーやトークンを直接書いてはならない。chezmoi のシークレットツール連携を使う：

1Password CLI

brew install --cask 1password 1password-cli
op signin

dot_ssh/config.tmpl：

Host github.com-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal
  PreferredAuthentications publickey

シークレットを参照する dot_env.tmpl：

export ANTHROPIC_API_KEY={{ onepasswordRead "op://Private/Anthropic/api_key" }}
export GITHUB_TOKEN={{ onepasswordRead "op://Private/GitHub/token" }}

chezmoi apply 実行時に 1Password から値を取得して平文の .env に書き込む。その平文ファイルは .gitignore されるため、リポジトリには含まれない。

Bitwarden / pass / age

それぞれ公式の chezmoi 連携がある — docs.chezmoi.io を参照。

6. ワークフロー

日常

# ~/.zshrc を直接編集した後
chezmoi diff       # 変更内容を確認
chezmoi add ~/.zshrc   # リポジトリに反映
chezmoi cd && git commit -am "tweak zshrc" && git push

別のマシンと同期

chezmoi update     # git pull＋apply

変更のプレビュー

chezmoi diff       # 適用前の変更を確認
chezmoi apply -v   # 詳細な適用

ソースを編集

chezmoi edit ~/.zshrc   # ソース（リポジトリ）を編集して自動適用

7. yadm — 最も軽量な代替

学習コストゼロが最優先なら yadm：

brew install yadm
yadm init
yadm add ~/.zshrc
yadm commit -m "init"
yadm remote add origin git@github.com:yourname/dotfiles.git
yadm push -u origin main
 
# 別のマシン
yadm clone git@github.com:yourname/dotfiles.git

コマンドは git と同一（バイナリが違うだけ）。欠点: マシン別分岐は .zshrc##os.Darwin のような alt ファイルに限られる。

8. raw シンボリックリンク＋Git

最小依存：

mkdir ~/dotfiles && cd ~/dotfiles
git init
mv ~/.zshrc ~/dotfiles/zshrc
ln -s ~/dotfiles/zshrc ~/.zshrc
 
# install.sh
#!/usr/bin/env bash
for f in zshrc gitconfig tmux.conf; do
  ln -sf "$HOME/dotfiles/$f" "$HOME/.$f"
done

シンプルだが、シークレット管理・分岐・ブートストラップは自分で実装する必要がある。多くの人が 1 年以内に chezmoi へ移行する。

確認

1. chezmoi diff → 変更なし（すべて適用済み）
2. ~/.zshrc を直接編集 → chezmoi diff で差分を確認
3. 新しいマシン（またはクリーンな VM）で chezmoi init --apply github.com/you/dotfiles → すべての dotfiles が復元される
4. テンプレートを変更後、chezmoi apply -v → ホスト名に基づいて異なる出力
5. 1Password 連携で chezmoi apply → ~/.env に平文が書かれるが、リポジトリには含まれない

トラブルシューティング

chezmoi apply が何も変えない

• chezmoi diff を確認。空なら期待通り。
• ファイルのパーミッション差異が変更を隠している場合がある — chezmoi apply --force を試す。

テンプレートの構文エラー

{{ ... }} は Go テンプレート。閉じ -}} の欠落と変数名のタイポが多い。chezmoi execute-template < dot_gitconfig.tmpl でドライランできる。

1Password 連携が失敗する

• op signin 後、セッションはデフォルトで約 30 分有効。eval $(op signin) を再実行。
• chezmoi.toml で 1Password を明示的に有効化（chezmoi edit-config）。

新しいマシンで SSH キーがない

SSH キー自体を dotfiles に保存してはならない（セキュリティ上の理由から）。新しいマシンでは新しいキーを生成して GitHub に登録する。chezmoi が管理するのは ~/.ssh/config などの設定ファイルのみ。

~/.zshrc を直接編集しても更新されない

chezmoi edit ~/.zshrc を使う（ソースを編集して自動適用）。またはソースを直接編集して chezmoi apply を実行。

参考リンク

• Mac 初期セットアップ — dotfiles より先に Homebrew など
• Mac↔Win ファイル同期 — ノート/プロジェクト用 Syncthing、dotfiles とは別
• chezmoi（公式）
• yadm

更新履歴

• 2026-05-12: 初稿。3 つのアプローチ比較＋chezmoi 実践セットアップ（テンプレート / シークレット / ワークフロー）＋5 つのトラブルシューティングケース。