better-chezmoi

Better chezmoi

inspect、preview、apply、verify のループを通じて chezmoi を使用します。ソースの状態、ターゲットの状態、ローカル設定、リモート Git、外部への影響を区別し、便利なコマンドによってユーザーの依頼範囲が暗黙のうちに拡大しないようにします。

運用上の取り決め

• 現在の参照情報：公式 chezmoi ドキュメントとリリース v2.71.0（2026-07-15 に確認）。
• ローカルで検証済みのコマンド範囲：macOS 上の chezmoi v2.70.2。ソース、保存先、設定、キャッシュ、永続状態を完全に分離したハーネスを含みます。
• バージョン規則：バージョン依存のフラグを使用する前に、chezmoi --version を実行し、chezmoi <command> --help を確認します。実行可能な構文はインストール済みのバイナリを基準とし、取得したドキュメントは最新の概念、例、新たにリリースされた動作の情報源とします。
• 権限規則：名前を指定したターゲットの追加、編集、適用、更新、マージ、削除を明示的に依頼された場合、その範囲の操作が許可されます。ただし、すべてのターゲットの適用、自動プッシュの有効化、リモート履歴の書き換え、シークレットの公開、ソースやターゲットの状態の破壊まで許可されたことにはなりません。
• 移植性：Windows ユーザーには PowerShell ネイティブの形式を示します。POSIX シェルの配列、コマンド置換、mktemp を Windows で移植可能な構文として提示しないでください。

タスクの振り分け

ユーザーの目的	読む資料	用途
ドットファイルの確認、追加、編集、取り込み、プレビュー、適用、同期	references/daily-workflows.md	日常作業で最も範囲の狭いループと、その検証方法を選びます
リポジトリの初期化、新しいマシンのブートストラップ、マシン固有の状態の分離	references/setup-and-machines.md	init、ソース／設定の配置、マシン間の境界を選びます
テンプレート、データ、シークレット、暗号化ファイル、スクリプトの構築やデバッグ	references/templates-secrets-and-scripts.md	レンダリングをテストし、機密データや副作用のあるデータをソース履歴に含めないようにします
ドリフト、競合、ロック、マージ、破壊的なクリーンアップの診断	references/recovery-and-safety.md	状態の所有者を特定し、元に戻せる復旧方法を選びます
正確なコマンド、フラグ、出力、終了時の動作の確認	references/commands.md	現在のコマンド形式と影響の分類を確認します
公式の最新情報が必要、または同梱コーパスの更新／検索	references/official-documentation.md	決定的なスクレーパーを実行し、出典情報を確認します

タスクに必要な行だけを読み込みます。単純な status の説明で、セットアップ、テンプレート、復旧の資料まで読み込む必要はありません。

まず影響を分類する

影響の分類	例	デフォルトの扱い
読み取り／確認	--version、help、source-path、target-path、status、diff、verify、doctor --no-network	必要に応じて実行します。テンプレートの評価、フック、キャッシュ済みの外部依存も考慮してください
ソースへの書き込み	add、edit、re-add、forget、init、Git pull	名前を指定したターゲットに限定します。対応している場合はプレビューし、ソースの差分を検証します
ターゲットへの書き込み	apply、edit --apply、デフォルトの update、init --apply	ユーザーが即時適用を明示的に依頼していない限り、先にプレビューします
ローカル設定／状態	edit-config、init 設定テンプレート、スクリプトの状態、purge	変更する前にパスと復旧方法を確認します
リモート／ネットワーク	Git fetch/pull、外部依存、パスワードマネージャー、自動コミット／プッシュ	読み取りの範囲を限定し、リモートへの書き込みやシークレットへのアクセスには明示的な許可を求めます
破壊的操作	destroy、広範な削除ルール、purge	正確な範囲、独立したバックアップ、可能な場合はプレビュー、実行後の条件確認を必須とします

--dry-run によって、chezmoi が保存先ディレクトリを変更しないことは保証されます。これは、あらゆる副作用を防ぐモードではありません。init はソースの Git 状態を作成する場合があり、ドライラン中もフックは実行され、テンプレートや外部依存がネットワークを必要とする依存関係を呼び出す場合があります。保証される範囲を正確に説明してください。

基本的なワークフロー

1. アクティブなコンテキストを確認する

役立つ最小限のコマンドを実行します。

chezmoi --version
chezmoi source-path
chezmoi target-path
chezmoi status --exclude=scripts

セットアップや依存関係の状態が不明な場合は、chezmoi doctor --no-network を使います。バンドルされたドキュメントにあるフラグを使う前に、該当するコマンドのローカルヘルプを確認してください。

完了条件： インストール済みのバージョン、ソースとターゲットのルート、要求されたターゲットの範囲、影響が及ぶ可能性のある対象が把握できていること。

2. 差分を確認する

通常のターゲットのずれやソースの編集の場合：

chezmoi diff --exclude=scripts --no-pager

ターゲットへの書き込みをプレビューする場合：

chezmoi apply --dry-run --verbose --exclude=scripts

非対話型プレビューが競合確認のプロンプトで停止する場合、ローカルヘルプとドライランフラグを確認した後に限り、--force を --dry-run と組み合わせて使えます。実際の適用では --force を使わないでください。

完了条件： 提案されたソースまたはターゲットの変更が確認でき、スクリプトとフックを考慮したうえで、変更を加える前に競合や想定外のターゲットが解決されていること。

3. 許可された影響のみを実行する

最も範囲を絞ったターゲット一覧を使います。要求の範囲が狭い場合は、対象を限定しない適用ではなく、単一のファイルまたはサブツリーを優先してください。chezmoi v2.71.0 以降では、非対話型の自動化で --error-on-conflict を使う前に、ローカルヘルプで利用できることを確認してください。古いバージョンでは、競合処理を --force に置き換えずに停止してください。

リモートへの影響とその範囲が明示的に許可されている場合に限り、git.autoPush を有効にするか、リモートへのプッシュを実行します。平文のシークレットをソース履歴に含めないでください。代わりに、ユーザーがサポートする暗号化またはシークレットマネージャーとの連携を使います。

完了条件： 指定されたソース、ターゲット、設定、またはリモートの範囲のみが変更され、コマンドがドキュメントに記載された成功結果を返していること。

4. 事後条件を確認する

次のうち1つ以上を使います。

chezmoi status --exclude=scripts
chezmoi diff --exclude=scripts --no-pager
chezmoi verify --exclude=scripts

結果を正しく解釈してください。diff は差分を表示していても 0 を返すことがあります。status はずれを2列で示します。verify は選択したターゲットが一致する場合に 0、一致しない場合に 1 を返します。

確認したバージョン、ソースとターゲットの範囲、実行したコマンド、確認された影響、残っているずれやスキップされた影響を報告してください。

完了条件： 要求された事後条件を独立して確認でき、ゼロ以外の結果が、想定されたずれ、競合、運用上の失敗、または未サポートの構文のいずれかに分類されていること。

公式ドキュメントコーパス

パッケージには、選択された公式ページの検索可能なスナップショットと、標準ライブラリのみを使った Python ツールが含まれています。

python3 scripts/official_docs.py search "error-on-conflict"
python3 scripts/official_docs.py list
python3 scripts/official_docs.py refresh

refresh は取得と比較を行いますが、バンドルされたスナップショットは置き換えません。コーパスの更新が許可されている場合に限り、正規のチェックアウトで --write を使ってください。置き換えられるのはローカルファイルであり、リモートリポジトリではありません。更新やソース一覧の変更の前に references/official-documentation.md を読み、出典の保持、ロールバックに安全な段階的置換、オフライン検証に役立ててください。

手順が失敗した場合や、スナップショットの内容がインストール済みのヘルプと食い違う場合は、該当バージョンに対応した公式の根拠を使って安全な代替手段を選んでください。情報源を利用できない場合は、不確実性をそのまま示してください。失敗したコマンド、バージョンまたは情報源、切り分け用の再現手順を添えて、正規のスキルの修正案を提示してください。インストール済みのコピーを書き換えたり、その修正案を公開したりしないでください。

注意点

1. update はプレビューではありません。通常、ソースリポジトリを取得し、ターゲットの変更を適用します。ユーザーが分離を望む場合は、update --apply=false を使うか、取得 → 差分確認 → 適用の順に確認しながら実行してください。
2. re-add はテンプレート化されたソースファイルを更新しません。代わりに edit、merge、または意図したテンプレートの変更を使ってください。
3. --source-path で指定した相対引数は、現在の作業ディレクトリを基準に解決されます。絶対パスのソースパスを使うか、ソースディレクトリから実行してください。
4. managed --format=json は、デフォルトのパス形式では必ずしも構造化 JSON になりません。出力の正確な形式を確認してください。v2.70.2 では、ドキュメントに記載されたキー付き構造を得るために --path-style=all が必要です。
5. 複数の chezmoi プロセスが、永続状態のロックを取り合うことがあります。chezmoi の run_ スクリプトから、chezmoi を再帰的に呼び出さないでください。

完了条件

ローカルのコマンド操作範囲を確認し、すべての影響がユーザーの指定範囲内に収まり、シークレットとリモートへの書き込みが制限され、要求された状態が検証され、バージョンやネットワークの制約が成功したかのように装うことなく報告されている場合にのみ、完了とします。