chezmoi の適用と配布

適用の前に確かめること

1. 適用元を確かめる。apply は commit ではなく、設定された source（chezmoi source-path で確認できる）の今の作業ツリー全体を配置先に反映する。merge していない変更を含んだブランチがほかにないか確かめる。未マージのブランチから配置した内容は、master からの次の apply で巻き戻る。worktree の内容を試すには、--source <worktree> を付け、対象のファイルを引数で絞る。この指定では run script が走らないので、mise の導入や settings の統合は別に行う。
2. chezmoi diff で配置が運ぶ変更を事前に見る。diff はディレクトリを引数に取っても配下を再帰しない（apply は再帰する）。同じ引数を渡しても、事前確認と適用とで範囲が違いうる。
3. chezmoi status の 2 列は意味が違う。1 列目は「前回の apply のあとに配置先が外から変わったか」で、この列に何かあると非対話の apply が確認を求めて止まる。2 列目は「apply が何を変えるか」。R の行は apply のたびに実行される run script の一覧で、未適用の差分ではない。MM は二重差分で、道具が自分の設定ファイルを書き換えるタイプで起き、放置すると apply のたびに巻き戻っては再実行を繰り返す。

権限のずれの防止と修復

1. Claude Code の Bash は umask 022、利用者のログインシェルは 002 で動いている。chezmoi は「あるべきモード」を実行プロセスの umask から計算する（ファイルは 0666 から、ディレクトリは 0777 から umask のビットを落とした値）。Claude から status と apply を実行するときは umask 002 を先に付ける。022 のままだと、002 で配置したファイルがすべて権限だけの差分として出る。
2. chezmoi の設定側に umask を固定しない。ディレクトリは設定値から mkdir したあとにプロセスの umask がさらに掛かるため、002 に固定すると 022 のシェルではディレクトリが 755 になって記録とずれる。umask はビットを落とすことしかできないので、設定値がプロセスの umask を含まないと意図した効き方をしない。
3. external の親ディレクトリは、source にエントリがなくても「暗黙のディレクトリ」として管理され、そのモードは実行時の umask で決まる。git はディレクトリのモードを記録しないので、clone 時の umask の名残が環境によってだけ問題になる。差分の再現がシェルごとに違うときは、この計算元を疑う。
4. run script の rsync には --no-perms --executability を付ける（短い -E は古い rsync で意味が違うので長い形で書く）。-a には --perms が含まれ、source が本当には持っていない情報（ディレクトリのモード、group と other のビット）までコピーする。git が記録するのは実行可能かどうかの 1 ビットである。転送元の末尾にスラッシュを付けると . 自身が転送対象になり、転送先のルートディレクトリのモードが上書きされる。exclude を付けてもルートのメタデータは守れない。
5. 権限だけのずれを直すときは、手で chmod するのではなく chezmoi apply --exclude scripts を使う。apply からスクリプトの実行だけを除けるので、chezmoi が覚えている「最後に書いた状態」と実体をそろえられる。
6. 同期や配置の結果は、終了コードだけでなく配置後のモードと中身を検査する。終了コードに出ない結果がある。

配布対象の追加と撤去

1. 配布を絞る手段は 3 つあり、効き方が違う。.chezmoiignore は「これから配置しない」だけで、配置先の既存ファイルには触らない。.chezmoiremove は全端末で無条件に消す。テンプレートの描画結果が空の target は、その端末でだけ消える。端末ごとに配置するかどうかを分けるなら、ignore ではなくテンプレートの中身を条件で空にする形が向いている。条件が変わった端末から、既に配置された分も自動で片付く。
2. .chezmoiignore は配置先のパスに対して、gitignore に近い glob で照合される。リポジトリ内の名前（dot_claude など）で書くと効かない。* はディレクトリの区切りをまたがないため、*.md が除外するのは直下だけで、下の階層はすり抜ける。ignore はほかのすべてに優先し、.chezmoiremove の対象からも外す。
3. source から消したファイルは配置先に残る。撤去するときは、消す commit の中で .chezmoiremove に同じパスを書く。書いた行は、対象のファイルがもう無くてもエラーにならないので残してよい。ほかの端末の apply でも同じ片付けが効く。
4. 撤去の過不足は git の履歴で機械的に確かめる。git log --diff-filter=D で source から消したファイルを拾い、「いま管理していない」「ignore に入っていない」「.chezmoiremove にまだ無い」の 3 条件で絞り込む。この端末に残っていないことは、ほかの端末に残っていないことの証明にならない。行の不足は残骸を残し、過剰な行は生きたファイルを消して apply 全体を止める。
5. chezmoi unmanaged は書き忘れの残りを見つけるが、merge 前のブランチから apply したファイルも同じように出る。消す前に出どころを確かめる。chezmoi managed には .chezmoiremove で消される target も載り続けるので、一覧の見た目で判断せず、apply の dry-run で結果を確かめる。端末条件で分けた変更は、dry-run を条件の両側（真と偽）で取る。片側だけの確認は「この端末では変わらない」ことしか分からない。
6. git で追跡するファイルを apply の script が書き換えるときは、追記だけにする。削除もすると、複数のマシンで差分が出続けて収束しない。apply の script が本体の作業ツリーに追記した行（新しいスキルを skill-approvals の一覧へ足す 1 行など）を、auto mode で本体に直接 commit すると自己改変として拒否される。利用者の了承後に worktree で同じ 1 行を commit して PR にすると通り、merge 後に本体を ff で追従させる。

対象を絞った apply と、run script が作るファイル

1. chezmoi apply <target> は対象のファイルだけを置き、run script は実行しない。引数に管理対象外のパスを 1 つでも混ぜると、ほかの引数も含めて何も配置せずに終わる。配置先に親ディレクトリがまだ無い新規ファイルを単体で指定すると、stat ... no such file or directory で失敗する。そのファイルのディレクトリごと指定して apply し直すと配置される。
2. settings.json のように、run script が複数の部品から組み立てて作るファイルは、target を指定しても更新されない。該当する script だけをレンダリングして単体で実行すると、ほかの script の副作用を避けられる。複数のソース断片から「配置済みのファイルを参照する」生成物は、部分適用のあとに参照先の実在を確かめる。
3. run_onchange_ は描画後の内容のハッシュが変わると再実行される。script を直すと、直した部分と無関係な処理まで一度は実行し直す。apply の序盤で sudo が要る script が落ちると、後続の反映がすべて止まる。
4. create_ は初回だけ作る属性である。後から雛形を変えても、既にできた配置先のリストには反映されない。
5. modify_ script は配置先のファイルを入力として受け取り、加工した結果を出す。実行時に道具が書き足した項目は apply をまたいで残るので、一時的な項目は配置先から直接消す。
6. 配置したあとに別の道具が書き換えるファイルを通常ファイルで管理すると、chezmoi は「外から変わった」とみなして確認を求め、非対話の apply 全体が exit 1 で止まり、run_after script も走らない。吸収する場所は 3 つあり（毎回 repo の内容で上書きする modify_、1 つにまとめる symlink、script でのコピー）、代わりに払うものがそれぞれ違う。もう 1 つの吸収は、配置先にだけ増えた行をソースへ取り込んで commit することである。Codex が ~/.codex/rules/default.rules に許可の行を書き足したことで apply が止まったとき、同じ行を home/dot_codex/rules/default.rules に足して commit してから apply し直すと通った。Codex が書き足すたびに再発するので同じ手順の繰り返しになり、根本策は別の文書に残す。
7. has changed since chezmoi last wrote it で止まるのは、persistent state が覚えている前回の内容と今のファイルが違うときである。2 つのファイルの更新時刻が一致するかは、利用者が直したのか道具が書いたのかを切り分ける最初の手がかりになる。
8. 配置済みのファイルと chezmoi cat を比べるときは、整形込みの差分をそのまま読まず、jq -S などで正規化してから比べる。複数のテンプレートが同じ部品を引数違いで呼ぶと、1 行の変更が複数の出力に効く。
9. 復旧の手順を文書に書くときは、その手順が仕組みの側で実際に動くかを確かめる。復旧の手順は書いた時点で誰も実行しないので、間違っていても気づきにくい（run_onchange の仕組み上「apply で作り直す」が効かない案内の例）。

配置と読み込みのずれ

• Mod の通知が届いても、settings に登録された hook の稼働を確認したことにはならない。両者は別の仕組みなので、hook 自身の記録を照合する。
• headless の検証では、settings.json の env が起動時に指定した CLAUDE_CODE_PLUGIN_DIRS を上書きしていないか確かめる。読み込まれた実装は、その実装だけが書く記録の形式と時刻でも照合する。

1. 同じ apply でも、反映の時点は 3 通りある。rule は次のターンから読まれ、Mod と agent 定義はセッションの起動時に読み込まれる。hook と CLI は呼び出しのたびに別プロセスで実行される。「apply したのに効かない」ときは、まずどの読み込み方かを確かめると原因を絞れる。
2. 動作の確認は 3 段階で行う。最初に、見本の入力を手で渡して script を単体で実行する（計器そのものの確認）。次に登録状態を確かめる（/hooks の一覧に出るか）。最後に、新規セッションで動作を確かめる。settings.json への登録はセッションの起動時に読み込まれるため、今のセッションが配備前に起動していれば、ここで確認しても「登録が無い」という当たり前の結果しか出ない。
3. hook を配置する前に、作業ツリー側で同じ入力を guard に流しておく。読み込めない hook を配置して、すべての Bash が拒否される事故を配置前に見つけられる。
4. 画面の通知とモデルへの入力は別の経路である。systemMessage は画面にだけ出て、モデルの入力には入らない。効果が無いとき、「条件を満たさなかった」のか「読み込まれていない」のかは、プロセスの起動時刻と起動時の環境変数で切り分ける。settings.json の env は起動後に読み直されて子プロセスに渡るが、プラグインのディレクトリは起動時にしか読まれない。Bash で見える環境変数だけでは、読み込まれたかどうかは分からない。
5. hook がまったく動かないときは、settings.json の disableAllHooks が true になっていないかを先に確かめる。run_onchange script は描画後の中身が変わらないと再実行せず、settings の統合もテンプレートに無いキーを残すため、chezmoi apply --force でも戻らない。/hooks の確認か jq の del(.disableAllHooks) で直接消すと、hook が戻る。

依存の供給網

1. バージョンがどこで決まるかを、変更の前に確かめる。要求側（mise の固定値）と供給側（action が検証済みとして抱える digest）が別の場所にあることがあり、1 つにはまとまらない。mise の短縮名は registry の別名で、実際の取得方法は registry 側が決める。切り替える前に mise registry <名前> で行き先を見る。短縮名が別のツールを指すことがある。
2. Renovate の分類は、どの manager が依存を見つけたかで決まる。同じ依存でも、workflow の with: 経由なら github-actions、package.json 経由なら npm の扱いになり、別のブランチに振り分けられる。mise の cargo:zizmor の depName は接頭辞ごと cargo:zizmor なので、規則は接頭辞を含めて書く。Renovate は mise の短縮名を自前の対応表で読み、表に無い名前は更新が黙って止まる。載っているかを別に確かめる。
3. 更新の設定は --platform=local --dry-run=lookup で、PR を作らずにどのブランチに何が入るかを確かめる。次の更新が来るまで結果が見えない設定の検証に向いている。
4. 待ち期間（minimumReleaseAge、mise の minimum_release_age）が効くのは、バージョンの範囲や latest から解決するときだけである。バージョンを固定した指定は待たずに入る。bun install --frozen-lockfile は解決を飛ばすので待ち期間の対象外で、配置時に改変を防ぐのは lock の integrity ハッシュである。グループ化しても待ち期間は依存ごとに評価され、manager が違えば片方にしか掛からない。
5. 取得は「落としてから実行」にする。curl -f URL | sh は、pipefail の無いシェルでは curl が何も出さずに落ちても sh が空の入力を 0 で読み終え、失敗が隠れる。ダウンロードの途中で切れると、前半だけが実行される。取得が完了する前に実行せず、失敗は後続の処理へ伝える。
6. digest の照合は、独立した上流の公開値とも比べる。Renovate は checksums.txt に今の digest が見つからないと tarball を自分で取得して hash を作る。その値は tarball との照合なら必ず一致するので、「配布物と sha が一致するか」の検査をすり抜ける。上流の公開値と照らす検査を別に置く。
7. 取得したものの照合は workflow の run: の中に書く。jactionlint の unverified-download は run の本文だけを見るため、照合を script ファイルに移すと検出が消える。それは直ったのではなく見えなくなっただけである。CI が実行する文面をそのまま取り出し、偽の curl に向けて実行すると、実際に走る文面そのものを検査できる。