chezmoiを使用したdotfiles管理のガイドです。
.
├── .chezmoiroot # chezmoiのソースディレクトリを指定
├── home/ # chezmoi管理下のdotfiles
│ ├── .chezmoi.toml.tmpl
│ ├── .chezmoiignore
│ ├── dot_Brewfile
│ ├── dot_config/
│ ├── dot_gitconfig.tmpl
│ ├── dot_gitignore_global
│ └── dot_zshrc.tmpl
├── .github/
└── README.md
.chezmoirootファイルによって、chezmoiはhome/ディレクトリをソースディレクトリとして認識します。この構造により、将来的にinstall/（セットアップスクリプト）やtests/（自動テスト）などのディレクトリを追加することが可能になります。
このdotfilesリポジトリでは、以下の3つのツールを役割分担して使用しています：
- 目的: dotfiles全体の運用管理
- 管理対象: 設定ファイル（
.zshrc,.gitconfig,.chezmoi.tomlなど） - 役割: 設定ファイルのバージョン管理、複数環境での同期、設定の適用・更新
- 目的: グローバルに適用したいアプリケーションの管理
- 管理対象: GUIアプリケーション、システム全体で使用するCLIツール
- 役割: macOSアプリケーションのインストール・管理、Brewfileによる一括管理
- 目的: プログラミングに特化した言語とCLIの管理
- 管理対象: プログラミング言語（Node.js, Python, Goなど）、開発用CLIツール
- 役割: 言語バージョンの切り替え、プロジェクト固有のツール管理
chezmoiのテンプレート機能を活用することで、環境やOS固有の設定を動的に管理できます。テンプレートファイルは.tmpl拡張子を持ち、Go の text/template シンタックスを使用します。
.chezmoi.toml.tmplファイルで変数を定義します：
[data]
name = "your-name"
email = "[email protected]"
# OS固有の設定
isMac = true # macOSの場合はtrue、そうでなければfalse
isLinux = false # Linuxの場合はtrue、そうでなければfalseこれらの変数は、他のテンプレートファイルから {{ .name }} や {{ .email }} のようにアクセスできます。
テンプレート内で {{ .chezmoi.os }} を使用してOSを判定し、環境に応じた設定を適用できます：
dot_gitconfig.tmpl では、OSに応じて適切なcredential helperを設定：
[user]
name = {{ .name }}
email = {{ .email }}
{{- if eq .chezmoi.os "darwin" }}
[credential]
helper = osxkeychain
{{- end }}
{{- if eq .chezmoi.os "linux" }}
[credential]
helper = cache --timeout=3600
{{- end }}dot_zshrc.tmpl では、OSに応じてPNPM_HOMEのパスを設定：
{{- if eq .chezmoi.os "darwin" }}
export PNPM_HOME="$HOME/Library/pnpm"
{{- else if eq .chezmoi.os "linux" }}
export PNPM_HOME="$HOME/.local/share/pnpm"
{{- end }}chezmoi init 実行時に、テンプレート変数の値を対話的に入力できます：
chezmoi init --promptString name=your-name --promptString [email protected]または、既存の.chezmoi.toml.tmplの変数定義を直接編集することもできます。
テンプレートが正しく展開されるかをテストできます：
# 特定のファイルのテンプレート展開結果を確認
chezmoi cat ~/.gitconfig
# すべての変更の差分を確認
chezmoi diff
# テンプレート変数の値を確認
chezmoi data- chezmoi templating公式ドキュメント
- テンプレートシンタックス：Go の text/template
- 利用可能な変数：
.chezmoi.os,.chezmoi.osRelease,.chezmoi.arch, etc.
初回設定時の流れ: 新しいPCではHomebrewがインストールされていない状態から始まります。以下の手順で段階的に環境を構築します。
# 公式のインストールスクリプトを使用
sh -c "$(curl -fsLS get.chezmoi.io)"chezmoi init https://github.com/yellow-seed/dotfiles.git
# chezmoiの設定ディレクトリに移動
chezmoi cd
# 設定をホームディレクトリに適用
chezmoi apply# Homebrewをインストール
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# BrewfileからHomebrewパッケージを一括インストール（miseも含む）
chezmoi cd
brew bundle install --file=dot_Brewfile# miseでツールをインストール（chezmoiで管理された設定から）
mise install注意: .zshrcにmiseの有効化設定が含まれているため、chezmoi apply実行後に新しいシェルセッションを開始すれば自動的にmiseが有効になります。
# chezmoiの設定ディレクトリに移動
chezmoi cd
# 現在のホームディレクトリの設定をchezmoiに追加
chezmoi add ~/.zshrc
chezmoi add ~/.gitconfig
chezmoi add ~/.config/mise/config.toml# 設定をホームディレクトリに適用
chezmoi apply
# 設定の差分を確認（実際には適用しない）
chezmoi diff
# 設定の状態を確認
chezmoi status# 設定ファイルを編集（chezmoiディレクトリ内のファイルを直接編集）
chezmoi edit ~/.zshrc
# または、chezmoi cdでディレクトリに移動してから編集
chezmoi cd
vim dot_zshrc# 設定ファイルを削除
chezmoi remove ~/.zshrc
# 設定ファイルを更新（ホームディレクトリの変更をchezmoiに反映）
chezmoi re-add ~/.zshrc
# 設定ファイルの情報を表示
chezmoi cat ~/.zshrcHomebrewでパッケージをインストール・アンインストールした際は、以下の一連の流れを実行してBrewfileを更新し、chezmoiで管理します。
# 現在のHomebrewパッケージをBrewfileに出力
brew bundle dump --no-vscode --describe --force --file=./install/macos/common/Brewfile
# chezmoiで管理対象に追加（初回のみ）
chezmoi add ./install/macos/common/Brewfile
# または、設定ファイルを更新（ホームディレクトリの変更をchezmoiに反映）
chezmoi re-add ./install/macos/common/Brewfile
# 変更をコミット
git add .
git commit -m "chore: Brewfileを更新"
git push origin main- Homebrewでパッケージをインストール・アンインストールした後は必ず上記の手順を実行する
--describeオプションでパッケージの説明も含めて出力--forceオプションで既存のBrewfileを上書き- 新しいPCでの環境構築時は
brew bundle installでBrewfileからパッケージを一括インストール可能
install/macos/common/brewfile.sh を使用することで、Brewfileからのパッケージインストールを自動化できます。
# Brewfileからパッケージを一括インストール
bash install/macos/common/brewfile.shこのスクリプトは以下の処理を行います：
- Homebrewがインストールされているか確認
install/macos/common/Brewfileが存在するか確認brew bundleを実行してパッケージをインストール
# Homebrewでパッケージをインストール
brew install <package-name>
# Brewfileを更新
brew bundle dump --describe --force --file=install/macos/common/Brewfile
# 変更をコミット
git add install/macos/common/Brewfile
git commit -m "chore: <package-name>をBrewfileに追加"
git push origin main# Homebrewでパッケージをアンインストール
brew uninstall <package-name>
# Brewfileを更新
brew bundle dump --describe --force --file=install/macos/common/Brewfile
# 変更をコミット
git add install/macos/common/Brewfile
git commit -m "chore: <package-name>をBrewfileから削除"
git push origin main新しいパッケージを追加した際は、以下の手順でテストできます：
# 1. Brewfileの構文チェック
brew bundle check --file=install/macos/common/Brewfile
# 2. インストールする内容を確認（実際にはインストールしない）
brew bundle list --file=install/macos/common/Brewfile
# 3. 実際にインストールを実行
brew bundle install --file=install/macos/common/Brewfile
# または自動インストールスクリプトを使用
bash install/macos/common/brewfile.shmiseでツールのバージョンを追加・変更・削除した際は、以下の手順で設定ファイルを更新し、chezmoiで管理します。
# miseの設定をchezmoiで管理対象に追加（初回のみ）
chezmoi add ~/.config/mise/config.toml
# miseでツールを追加・変更・削除
mise use [email protected]
mise use [email protected]
mise uninstall [email protected]
# 設定ファイルを更新（ホームディレクトリの変更をchezmoiに反映）
chezmoi re-add ~/.config/mise/config.toml
# 変更をコミット
git add .
git commit -m "chore: mise設定を更新"
git push origin main- miseでツールのバージョンを変更した後は必ず上記の手順を実行する
chezmoi re-addでホームディレクトリの変更をchezmoiに反映- 新しいPCでの環境構築時は
mise installで設定ファイルからツールを一括インストール可能 - miseの設定は
~/.config/mise/config.tomlに保存される
- 既存のPC設定を単純に反映する場合: 直接pushしても問題ありません
- 新しい設定や機能追加: ブランチを作成して作業することを推奨します
# 新しいブランチを作成
git checkout -b feature/add-new-config
# 設定を追加・編集
chezmoi add ~/.newconfig
chezmoi edit ~/.newconfig
# 変更をコミット
git add .
git commit -m "feat: 新しい設定ファイルを追加"
# ブランチをプッシュ
git push origin feature/add-new-config
# プルリクエストを作成してマージ# 修正用ブランチを作成
git checkout -b fix/update-config
# 設定を修正
chezmoi edit ~/.zshrc
# 変更をコミット
git add .
git commit -m "fix: zshrcの設定を更新"
# ブランチをプッシュしてプルリクエスト
git push origin fix/update-config# 既存のPC設定をそのまま反映する場合
chezmoi add ~/.existingconfig
git add .
git commit -m "chore: 既存設定を反映"
git push origin mainfeature/- 新機能追加fix/- バグ修正・設定修正chore/- 既存設定の反映・メンテナンスdocs/- ドキュメント更新
# 新しいPCでの初期設定
chezmoi apply
# 設定変更の一連の流れ
chezmoi edit ~/.zshrc
chezmoi diff
chezmoi apply
git add .
git commit -m "feat: zshrcの設定を更新"
git push origin main
# 設定の確認
chezmoi status
chezmoi cat ~/.zshrcこのリポジトリでは、シェルスクリプトの品質向上のためにShellCheckとshfmtを使用しています。
ShellCheckはシェルスクリプトの文法エラー、潜在的なバグ、非推奨な書き方を検出します。
インストール:
# macOS
brew install shellcheck
# Ubuntu
sudo apt-get install shellcheck
# VS Code拡張機能（オプション）
# Brewfileに以下を追加して `brew bundle install` を実行
# vscode "timonwong.shellcheck"ローカルでの実行:
# 単一ファイルをチェック
shellcheck install/macos/common/brew.sh
# すべてのシェルスクリプトをチェック
shellcheck install/**/*.sh scripts/**/*.sh setup.sh
# 特定のディレクトリ配下をチェック
shellcheck install/macos/common/*.shVS Code統合:
- ShellCheck拡張機能（
timonwong.shellcheck）を手動でインストール可能 - エディタ内でリアルタイムに警告を表示
CI/CD統合:
.github/workflows/shellcheck.ymlでPR時に自動チェック- すべてのシェルスクリプトが対象
設定ファイル:
.shellcheckrcでプロジェクト共通のルールを設定- 現在の設定: SC1091（sourced filesのフォロー）を無効化
shfmtはシェルスクリプトの自動フォーマットツールです。
インストール:
# mise経由（推奨）
mise use shfmt@latest
# または Homebrew
brew install shfmt使用方法:
# フォーマットの確認（変更なし）
shfmt -d .
# 自動フォーマット（ファイルを上書き）
shfmt -w .
# 特定のファイルのみフォーマット
shfmt -w install/macos/common/brew.shシェルスクリプトの動作を検証するため、BATS (Bash Automated Testing System)を使用しています。
すべてのテストを実行:
# macOSの場合
bash scripts/macos/run_unit_test.sh
# Ubuntuの場合
bash scripts/ubuntu/run_unit_test.sh特定のテストファイルのみ実行:
# BATSコマンドで直接実行
bats tests/install/macos/common/brew.bats
# ShellCheckのテスト
bats tests/files/shellcheck.batsシェルスクリプトを作成・修正する際は、以下の規約に従ってください：
- エラーハンドリング: 必ず
set -Eeuo pipefailを設定 - ShellCheck検証: すべてのスクリプトはShellCheckをパス
- コメント: 日本語でのコメント推奨
- 変数命名: 環境変数は
UPPER_CASE、ローカル変数はlower_case - テスト: 新しいスクリプトには対応するBATSテストを作成
chezmoi applyを実行する前にchezmoi diffで変更内容を確認することを推奨- 重要な設定変更は必ずブランチを作成して作業する
- コミットメッセージはConventional Commitsの形式に従う