ノート

手動 dotfiles から Chezmoi への移行 (随時更新)

#Misc

更新日: 2025年9月4日

注意事項

chezmoiはdotfiles管理ツールだが、シンボリックリンクを貼るわけではない。 簡単なdotfilesを不必要に複雑化させる可能性があるので、導入には注意が必要。

目的

Ubuntuマシンを増やすため、手動管理の dotfiles（~/dotfilesをシンボリックリンクでホームに展開, シェルスクリプト）を、chezmoi による統一的・クロスプラットフォームな管理体制へ移行する。
最終的に Ubuntu と macOS 双方の設定を1リポジトリで扱うことを目標とする。

現状

Chezmoi導入前のdotfilesリポジトリは、簡略化すると、

~/dotfiles/
├── home # 設定ファイル群
├── scripts # シェルスクリプト群
└── その他

.がついた設定ファイルと運用のためのスクリプトを格納していた。 $HOMEには、home 以下のファイルをシンボリックリンクで展開していた。

この構成は単純だが、

  • OSごとの分岐 (if文で切り分け)
  • 機密情報（ssh, tokenなど）の管理
  • 新マシン初期化の自動化 が面倒そうだったので、chezmoi に移行することにした。(移行しなくても良いのだが、学習目的も兼ねている)

Chezmoiとは

chezmoi (シェモワ、仏: 「私の家」)は Go 製の dotfiles管理ツール。

クロスプラットフォーム対応、テンプレート機能、機密情報の暗号化管理などが特徴。

dotfilesの管理をしてくれるということで、シェルスクリプトを自作する手間が省ける。

移行フロー

リポジトリ持ってくる

chezmoi init $GithubUserName

これで $HOME/.local/share/chezmoi に $GithubUserName/dotfiles.git が clone される。

ついでにchezmoi/home以下の設定ファイルを削除(これはchezmoiがクローンしてきたディレクトリだから、本体には関係ない)

rm -rf $HOME/.local/share/chezmoi/home/.*

ソースディレクトリを変更

chezmoiではデフォルトではリポジトリのルートにdotfilesが置かれるがhome以下におきたいので、

chezmoi cd
touch .chezmoiroot

で.chezmoirootを作成し、ソースディレクトリを変更する。ファイルの中身は

home

のみ。

dotfilesを取り込む

chezmoi add --follow ~/.bash_profile
chezmoi add --follow ~/.zshrc
chezmoi add --follow ~/.zprofile
chezmoi add --follow ~/.profile
chezmoi add --follow ~/.gitconfig
chezmoi add --follow ~/.vimrc
chezmoi add --follow ~/.clang-format
chezmoi add --follow ~/.condarc
chezmoi add ~/.config/karabiner
chezmoi add ~/.config/nvim

chezmoi add ファイル名で、指定したファイルを管理下に置く。ただし、すでにホームディレクトリにはシンボリックリンクが貼られているので、 --follow オプションをつけて、シンボリックリンクの実体を取り込む。(ただし、ディレクトリに対しては --follow は使えない)

機密情報の取り込み

私はBitwardenを使っているので、Bitwarden CLIとchezmoiを連携させて、機密情報を暗号化して管理する。詳しくは公式ドキュメントを参照。

brew install bitwarden-cli # macOSの場合
bw login # Bitwardenにログイン
bw unlock # Bitwardenのロック解除 (求められたら)

unlockすると、セッションキーが出るので、これをBW_SESSION 環境変数にセットする。

export BW_SESSION="xxxxxxxxxxxxxxxx"

このセッションキーを環境変数にセットしておくと、chezmoiがBitwardenから秘密情報を取得できるようになる。

ちなみに、chezmoi の設定（chezmoi.toml / .json）で次のように書くと、BW_SESSION が未設定のときに bw unlock を自動で呼び出すようになる。

{
  "bitwarden": {
    "unlock": "auto"
  }
}
chezmoi secret bitwarden init

結果：

$HOME/.local/share/chezmoi/
└── dot_zshrc

Chezmoiの情報については 公式ドキュメント を参照。

既存シンボリックリンクの扱い

既に ~/dotfiles にシンボリックリンクを貼っている場合、
chezmoi add ~/.zshrc はリンクを追跡して実体を取り込むため、
リンクを削除せずそのまま add してよい。

移行の流れ：

chezmoi init
chezmoi add ~/.zshrc
chezmoi add ~/.config/nvim
chezmoi diff
chezmoi apply

完了後、不要になったシンボリックリンクを削除：

find $HOME -type l -lname '*dotfiles*' -delete

OSごとの設定分岐

Chezmoi のテンプレート機構 (.tmpl) を用いる。

例：dot_zshrc.tmpl

{{ if eq .chezmoi.os "darwin" }}
# macOS-specific
export PATH="/opt/homebrew/bin:$PATH"
{{ else if eq .chezmoi.os "linux" }}
# Linux-specific
export PATH="/usr/local/bin:$PATH"
{{ end }}

chezmoi apply 時に自動的に OS に応じた内容が展開される。

秘密情報の分離

chezmoi は encrypted_ プレフィックスによって機密ファイルを暗号化管理できる：

chezmoi add --encrypt ~/.ssh/config
chezmoi secret add github_token

暗号化には GPG か age を利用。

Ubuntu と macOS の統合構成

$GithubUserName/dotfiles.git の最終構成例：

dotfiles/
├── dot_zshrc.tmpl
├── dot_gitconfig
├── private_dot_ssh/
│   └── config.age
├── run_once_install-packages.sh.tmpl
└── README.md
  • run_once_*.sh は初回実行時に自動で動くセットアップスクリプト。
  • OS 分岐を .tmpl に埋め込み、共通リポジトリで両環境を再現可能。

運用ワークフロー

  1. 新環境セットアップ：

    chezmoi init $GithubUserName
chezmoi apply

  2. 変更の反映：

    chezmoi edit ~/.zshrc
chezmoi diff
chezmoi apply

  3. GitHub へ push：

    chezmoi cd
git add .
git commit -m "Update macOS zshrc"
git push origin main

今後の拡張

  • run_once スクリプトで brew/apt を自動インストール
  • テンプレート中で環境変数に応じた分岐
  • chezmoi update で dotfiles のローリング更新

コメント