chezmoi-workflows

Chezmoi ワークフロー

自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある場合、パラメーターがずれている場合、または回避策が必要だった場合は、先延ばしにせず、このファイルをすぐに修正してください。実際に再現できる問題がある場合にのみ更新してください。

このスキルを使う場面

次のような場合に、このスキルを使用します。

• dotfiles を Git リポジトリにバックアップする
• 複数のマシン間で設定ファイルを同期する
• シェル設定、エディター設定、その他の dotfiles の変更を追跡する
• chezmoi でテンプレート化された設定を管理する
• ソースとターゲット間で dotfiles に差異が生じた場合にトラブルシューティングする

アーキテクチャ

コンポーネント	場所	目的
ソース	$(chezmoi source-path)	dotfile テンプレートを含む Git リポジトリ
ターゲット	~/	ホームディレクトリ（デプロイされたファイル）
リモート	GitHub（プライベートを推奨）	マシン間の同期とバックアップ
設定	~/.config/chezmoi/chezmoi.toml	ユーザー設定

---

1. ステータスを確認する

chezmoi source-path                    # Show source directory
chezmoi git -- remote -v               # Show GitHub remote
chezmoi status                         # Show drift between source and target
chezmoi managed | wc -l                # Count tracked files

---

2. ファイルの変更を追跡する

設定ファイルを編集した後、chezmoi に追加します。

chezmoi status                         # 1. Verify file shows as modified
chezmoi diff ~/.zshrc                  # 2. Review changes
chezmoi add ~/.zshrc                   # 3. Add to source (auto-commits if configured)
chezmoi git -- log -1 --oneline        # 4. Verify commit created
chezmoi git -- push                    # 5. Push to remote

---

3. 新しいファイルを追跡する

これまで追跡していなかった設定ファイルを追加します。

chezmoi add ~/.config/app/config.toml  # 1. Add file to source
chezmoi managed | grep app             # 2. Verify in managed list
chezmoi git -- push                    # 3. Push to remote

---

4. リモートから同期する

GitHub から変更を取得し、ホームディレクトリに適用します。

chezmoi update                         # 1. Pull + apply (single command)
chezmoi verify                         # 2. Verify all files match source
chezmoi status                         # 3. Confirm no drift

---

5. すべての変更をプッシュする

変更された追跡対象ファイルをまとめてリモートに同期します。

chezmoi status                         # 1. Review all drift
chezmoi re-add                         # 2. Re-add all managed files (auto-commits)
chezmoi git -- push                    # 3. Push to remote

---

6. 初回セットアップ

chezmoi をインストールする

brew install chezmoi                   # macOS

初期化する（新規スタート）

/usr/bin/env bash << 'CONFIG_EOF'
chezmoi init                           # Create empty source
chezmoi add ~/.zshrc ~/.gitconfig      # Add first files
gh repo create dotfiles --private --source="$(chezmoi source-path)" --push
CONFIG_EOF

初期化する（既存のリポジトリをクローン）

chezmoi init [email protected]:<user>/dotfiles.git
chezmoi apply                          # Deploy to home directory

---

7. ソースディレクトリを設定する

ソースをカスタムの場所に移動します（例：複数の SSH アカウントを使う場合）。

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
mv "$(chezmoi source-path)" ~/path/to/dotfiles
SKILL_SCRIPT_EOF

~/.config/chezmoi/chezmoi.toml を編集します。

sourceDir = "~/path/to/dotfiles"

確認します。

chezmoi source-path                    # Should show new location

---

8. リモートを変更する

別の GitHub アカウントまたはリポジトリに切り替えます。

chezmoi git -- remote -v                                              # View current
chezmoi git -- remote set-url origin [email protected]:<user>/<repo>.git # Change
chezmoi git -- push -u origin main                                    # Push to new remote

---

9. マージコンフリクトを解決する

/usr/bin/env bash << 'GIT_EOF'
chezmoi git -- status                  # 1. Identify conflicted files
chezmoi git -- diff                    # 2. Review conflicts
# Manually edit files in $(chezmoi source-path)
chezmoi git -- add <resolved-files>    # 3. Stage resolved files
chezmoi git -- commit -m "Resolve merge conflict"
chezmoi apply                          # 4. Apply to home directory
chezmoi git -- push                    # 5. Push resolution
GIT_EOF

---

10. 検証（SLO）

主要な操作の後、システムの状態を確認します。

chezmoi verify                         # Exit 0 = all files match source
chezmoi diff                           # Empty = no drift
chezmoi managed                        # Lists all tracked files
chezmoi git -- log --oneline -3        # Recent commit history

---

11. ファイルの追跡を解除する

ファイルをホームディレクトリから削除せずに、追跡を停止します。

chezmoi managed | grep config.local     # 1. Confirm file is tracked
chezmoi forget --force ~/.config/app/config.local.toml  # 2. Remove from source (--force skips TTY prompt)
chezmoi git -- push                     # 3. Push removal to remote
ls ~/.config/app/config.local.toml      # 4. Verify file still exists in home

使用する場面：マシン固有の設定、同期すべきでないシークレットを含むファイル、誤って追加したファイル。

---

12. テンプレートを管理する

Go テンプレートを使って、OS やアーキテクチャに応じた設定を作成します。

既存のファイルをテンプレートに変換する

chezmoi add --template ~/.config/app/config.toml  # 1. Add as template (creates .tmpl suffix in source)
chezmoi edit ~/.config/app/config.toml             # 2. Edit template in $EDITOR (helix)
chezmoi diff ~/.config/app/config.toml             # 3. Preview what would change
chezmoi apply ~/.config/app/config.toml            # 4. Apply rendered template to home

よく使われるテンプレートパターン

# OS-conditional block
{{ if eq .chezmoi.os "darwin" -}}
export HOMEBREW_PREFIX="/opt/homebrew"
{{ else if eq .chezmoi.os "linux" -}}
export HOMEBREW_PREFIX="/home/linuxbrew/.linuxbrew"
{{ end -}}

# Architecture-conditional
{{ if eq .chezmoi.arch "arm64" -}}
ARCH="aarch64"
{{ else -}}
ARCH="x86_64"
{{ end -}}

# Custom data from chezmoi.toml [data] section
git_name = "{{ .git.name }}"
git_email = "{{ .git.email }}"

# 1Password secret (requires op CLI)
api_key = {{ onepasswordRead "op://Vault/Item/Field" }}

テンプレートが正しくレンダリングされることを確認する

chezmoi execute-template < "$(chezmoi source-path)/dot_config/app/config.toml.tmpl"
chezmoi cat ~/.config/app/config.toml   # Show rendered output without applying

---

13. 安全に更新する（適用前に差分を確認）

リモートから変更を取得し、確認ステップを挟みます。何も確認せずに chezmoi update を実行するより安全です。

chezmoi git -- pull                    # 1. Pull source changes only (no apply)
chezmoi diff                           # 2. Review what WOULD change in home directory
chezmoi apply --dry-run --verbose      # 3. Dry run — shows actions without executing
chezmoi apply                          # 4. Apply after review
chezmoi status                         # 5. Confirm clean state

使用する場面：別のマシンで行われた変更を取得する場合、または同期の間隔が長く空いた場合に使います。ローカルでの編集が予期せず上書きされるのを防げます。

---

14. Doctor（診断）

chezmoi のセットアップと環境をトラブルシューティングします。

chezmoi doctor                         # Full diagnostic — checks all components

確認する主な項目：

チェック	期待される値	失敗した場合の意味
config-file	found ~/.config/chezmoi/chezmoi.toml	設定がない、またはパスが間違っている
source-dir	~/gh/vjspc/dotfiles is a git working tree (clean)	ソースに未コミットの変更がある、または Git リポジトリではない
git-command	found /opt/homebrew/bin/git	Git がインストールされていない
edit-command	found /opt/homebrew/bin/hx	エディターが設定されていない
1password	found /opt/homebrew/bin/op	テンプレートで 1Password CLI が必要
age/gpg	info = optional	暗号化ファイルにのみ必要

chezmoi doctor | grep -v "^ok"         # Show only warnings and errors

参考資料

• セットアップガイド - インストール、複数の GitHub アカウント、移行
• プロンプトパターン - 詳細なワークフローの例
• 設定 - chezmoi.toml の設定、テンプレート
• シークレットの検出 - 検出されたシークレットの処理

Chezmoi のドキュメント: https://www.chezmoi.io/reference/

---

トラブルシューティング

問題	原因	解決策
chezmoi が見つからない	インストールされていない	brew install chezmoi でインストールする
ソースパスが空	初期化されていない	chezmoi init を実行する
Git リモートが設定されていない	GitHub リポジトリがない	chezmoi git -- remote add origin URL を実行する
適用に失敗する	テンプレートエラー	chezmoi diff でテンプレート構文を確認する
マージコンフリクト	ソースとターゲットが分岐している	chezmoi merge で解決する
シークレットが検出された	認証情報がプレーンテキストで記述されている	1Password/Doppler と chezmoi のテンプレートを使用する
forget に TTY が必要	対話形式での確認	chezmoi forget --force <path> を使用する
テンプレートが見つからない	.tmpl サフィックスがない	chezmoi add --template で .tmpl を作成する

実行後の振り返り

このスキルの実行後、終了する前に確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった手順またはエラー表を修正してください。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーター表を更新して整合させてください。
3. 回避策が必要でしたか？ — 別のフラグや追加手順などで対応した場合は、次回同じ回避策が必要にならないよう、この SKILL.md を更新してください。

問題が実際に発生し、再現可能な場合にのみ更新してください。憶測による更新は避けてください。