GNU stow から chezmoi への移行：Mac dotfiles 管理の再構築

長年、GNU

stow

chezmoi

運用環境と課題

マシン構成

私の環境には以下の 3 台の Mac が存在します。

• 「仕事用」MacBook Pro
• 「個人用」MacBook Air
• 「Mac Mini」：小規模な個人サーバーとして運用し、他の 2 台から主に SSH で接続。

これら 3 台はすべて同じ dotfiles を共有しています。また、数台の Linux ボックスを仮想マシンとして維持していますが、それらの設定は Ansible でプロビジョニングするため頻繁には必要としません。このワークフローは厳密にデスクトップ用マシン向けです。

stow を離脱した理由

stow は単一マシンの場合は非常に優れていましたが、マルチデバイス環境では以下の問題が生じました。

• シンボリックリンクの双方向性

  • stow はリンクが「双方向」に機能するモデルです。
  • どのマシンでも設定ファイルを編集すると、変更はそのマシンの Git クローンを通じて直接書き込まれてしまいます。
  • 結果として、数ヶ月後には Air 上で行いながら記憶していない変更が見つかり、Pro でプッシュした内容と競合します。3 つのクローンを収束させるのは面倒でした。

• 新マシンへの導入が困難

  • stow は実際のファイル上へのリンク作成ができないため、新規 Mac に Homebrew やツールをインストールした時点で

    ~/.zprofile

    や

    ~/.gitconfig

    などが既に存在してしまいます。
  • セットアップ手順：リポジトリのクローン → 競合するファイルの手動削除 → パッケージごとの再ストウ化 → ナメ付けの記録など、手間がかかるものでした。

• 機能の制限

  • stow はファイルのみを扱います。
  • Homebrew パッケージや macOS 自体の設定は、実行順序を管理する別々のスクリプト記述が必要です。

chezmoi の仕組みと特徴

chezmoi は

~/.local/share/chezmoi

ファイル名の符号化

• 例：

  chezmoi add ~/.zshrc

  を実行すると、実際のファイルはこのディレクトリにコピーされ、名前が

  dot_zshrc

  となります。
• ディレクトリ構造はホームディレクトリを反映し、ドット設定（dot）はすべて

  dot_

  プレフィックス で管理されます（例：

  ~/.config/gh/config.yml

  →

  dot_config/gh/config.yml

  ）。
• 名前付けは手動ではなく、

  chezmoi add

  コマンドが自動的にパスから導き出してくれます。

メタデータと属性

• _private

  プレフィックス：ファイルからグループおよびワールドへのアクセス権限を除去します（例：

  dot_config/gh/config.yml

  の設定）。

• .tmpl

  サフィックス：ファイルを Go テンプレートに変換し、マシン固有のデータを参照できるようにします。

「apply」の動作

chezmoi apply

dot_zshrc

~/.zshrc

• コピーはシンボリックリンクではなく、実際のファイル です。
• ソースディレクトリが唯一の情報源となります。
• ホームディレクトリのファイルとソースの一致度が保たれていない場合、

  chezmoi diff

  で差分を表示し、次の apply で元通りに戻してくれます。

最も気に入っている点：シンボリックリンクによる自動的な双方向書き込みがないため、リポジトリへの変更は意図的に行うことが保証されます。

リポジトリの構成概要

chezmoi cd

~/.local/share/chezmoi
├── .chezmoi.toml.tmpl          # chezmoi 設定テンプレート
├── .chezmoiignore              # ソースに残しホームに書込まないファイルの除外リスト
├── .chezmoiscripts             # apply 時の実行スクリプト
│   └── macos/                  # macOS 用スクリプト群
├── .gitignore
├── Brewfile                    # Homebrew パッケージ管理
├── README.md
├── dot_agents/                 # エージェント向けスキル (skills)
├── dot_claude/                 # Claude Code の設定とマッピング
├── dot_codex/                  # Codex の設定 (private_config.toml)
├── dot_config/                 # 各種設定 (gh, ghostty など)
├── dot_gitconfig               # アイデンティティを分断した git 設定
├── dot_shellcheckrc
└── dot_zsh_aliases             # zshrc のソースもここに格納
    └── dot_zshrc

Git とアイデンティティの分離

すべてのプロジェクトは以下の 2 つのディレクトリ下に存在し、主に gitconfig でルーターしています。

• ~/canvas/werk/

  ：仕事用（業務用メールアドレス）

• ~/canvas/pers/

  ：個人用（個人的なメールアドレス）

[includeIf "gitdir:~/canvas/pers/"]
    path = ~/.gitconfig-pers

[includeIf "gitdir:~/canvas/werk/"]
    path = ~/.gitconfig-werk

Note: この仕組みは chezmoi テンプレティングではなく、通常の Git 機能ですが、

chezmoi

マシン固有の設定

トップにある

.chezmoi.toml.tml

~/.config/chezmoi/chezmoi.toml

{{- $machineName := promptStringOnce . "machineName" "machineName" .chezmoi.hostname -}}

[data]
    machineName = {{ $machineName | quote }}

これはリポジトリ全体における唯一のマシン固有データです。

除外ファイルの設定

.chezmoiignore

README.md

Brewfile

Brewfile.lock.json

.gitignore

新しい Mac のセットアップ（ブートストラップ）

最初に Homebrew を導入した後、以下のコマンドだけで全設定が可能です。

brew install chezmoi
chezmoi init --apply \
    --promptString machineName=mini \
    https://github.com/rednafi/dotfiles.git

• --apply

  オプション：追跡されているファイルを即時に配置します。

• --promptString

  ：対話形式ではなく、マシン名の質問に事前回答を与えます。

スクリプトの自動実行

.chezmoiscripts/

apply

• before_

  ：ファイル配置前に実行。

• after_

  ：ファイル配置後に実行。

• run_onchange_

  ：最初の apply で発火し、以降は内容変更時のみ発火（onchange 手法）。

Homebrew & macOS 設定スクリプト

Homebrew パッケージのインストールや macOS 自体の設定は、以下の順序で処理されます。

Brewfile の管理

Brewfile ハッシュをコメントに埋め込み、ファイルが変更されたら自動的に再実行するロジックです。

#!/usr/bin/env bash
# Brewfile checksum: {{ include "Brewfile" | sha256sum }}

# ... elided

brewfile={{ joinPath .chezmoi.sourceDir "Brewfile" | quote }}

"$brew_bin" bundle check --no-upgrade --file "$brewfile" >/dev/null 2>&1 \
    || "$brew_bin" bundle install --no-upgrade --file "$brewfile"

Brewfile の例：

brew "chezmoi"
brew "fzf"
brew "gh"
brew "micro"
brew "ripgrep"
brew "uv"

cask "claude-code"
cask "codex"
cask "ghostty"
cask "raycast"

macOS 設定スクリプト

1. マシンの初期化：ホスト名の設定、システムデフォルトの書き込み。
2. アニメーション無効化：

   defaults write

   を経由して UI アニメーションを無効にするスクリプト。

すべてのスクリプトは

Darwin

日常運用のルーティン

全体の作業フローは以下の約 5 つのコマンドで行えます。

1. 編集（ソースから）

通常はソースから編集します。

chezmoi edit --apply

chezmoi edit --apply ~/.zshrc

逆方向の編集（ライブファイル）

インストーラーによる追加や、直感的な編集からライブファイルを直接改訂する場合、ホームディレクトリがソースよりも先行し、apply で変更を元に戻すことになります。これを防ぐには

chezmoi re-add

# 単一ファイルの再インポート
chezmoi re-add ~/.zshrc

# ※複数のファイルがソースより先に移動している場合も一括で処理可能

2. Git の共有

リポジトリの状態を整理し、Git でコミットします。

chezmoi cd
git add -A
git commit -m "Update dotfiles"
git push
exit

他のマシンを追跡するには：

chezmoi init --apply https://github.com/rednafi/dotfiles.git

3. 差分の確認と適用

確認してから適用します。

chezmoi git pull -- --autostash --rebase
chezmoi diff
chezmoi apply --verbose

4. Brew の同期

パッケージが Brewfile と同步外れた場合、以下のコマンドで報告および修正を行います。

brew bundle check --no-upgrade --file "$(chezmoi source-path)/Brewfile"
brew outdated --greedy
brew bundle cleanup --file "$(chezmoi source-path)/Brewfile"

エージェントスキルの追跡

リポジトリへの最新な追加は、LLM エージェント向けのスキルファイルです。

スキルフォルダ構造

スキルとは、

SKILL.md

• SKILL.md

  ：フロントマター（タイトル・説明）と指示を含みます。
• Anthropic の標準に従い、どこでも動作するようオープンスタンダードを採用しています。

環境での検出箇所

• Codex：

  ~/.agents/skills

  をデフォルトとして検出。
• Claude Code：まだこの慣習に追いついておらず、

  ~/.claude/skills

  を探求します。

シンボリックリンクの統一 (

dot_claude

)

Claude Code が標準的な

~/.agents/skills

dot_claude/symlink_skills.tmpl

{{ .chezmoi.homeDir }}/.agents/skills

この仕組みにより、以下の 3 つの要素が協力して機能します。

1. ターゲットマッピング：

   ~/.claude/skills

   を

   dot_claude/

   を通じてマッピング。
2. リンク指定：

   symlink_

   プレフィックスにより、内容を示す場所へのシンボリックリンクとして作成するよう指示。
3. テンプレート展開：

   .tmpl

   サフィックスにより、

   {{ .chezmoi.homeDir }}

   がマシン固有に展開されます。

結果：

lrwxr-xr-x 1 rednafi staff 29 Jun 11 17:37 /Users/rednafi/.claude/skills -> /Users/rednafi/.agents/skills

皮肉：stow を捨ててシンボリックリンクから逃れ、結局 chezmoi が管理するのは「私が必要な唯一つのシンボリックリンク」であるという状況に至りました。しかし、Anthropic の仕様追従のため仕方ありません。これで両方のエージェントが同じスキルを読み取り、Git は単一のコピーを保持できます。

利用のススメ

ここにあるものはすべて私の dotfiles リポジトリ上にあります。有用そうなものをご利用ください。