設定とリポジトリ形式のアップグレード

manifest と settings のマイグレーション

dotweave は設定ファイルを読み込むときにマイグレーションします。専用のアップグレードコマンドはなく、古い manifest.jsonc や settings.jsonc を最初に開いたコマンドが、バージョンを 1 段ずつ進めます。

書き直す前に、dotweave は元のファイルの隣へ <filename>.v<originalVersion>.bak という名前でバックアップを書き出します。バージョン 7 の manifest をマイグレーションすれば manifest.jsonc.v7.bak が残り、バージョン 2 の settings なら settings.jsonc.v2.bak が残ります。書き直し自体はアトミックで、マイグレーション結果が意味的な検証を通ったあとにだけ実行されます。そのため不正なマイグレーション結果が保存されることはありません。

manifest.jsonc の現在のバージョンは 9 で、バージョン 7 と 8 を受け付けてマイグレーションします。settings.jsonc の現在のバージョンは 3 で、バージョン 2 を受け付けてマイグレーションします。

manifest の 7 から 8 への手順は、プロファイル名をレジストリへ引き上げます。以前はプロファイル名が個々の項目にしか存在しませんでした。マイグレーションはその名前を集め、ソートしてトップレベルの profiles 配列に入れます。default は暗黙のプロファイルなので除かれます。settings の 2 から 3 への手順は、古い age セクションを削除します。

書き直しは解析済みのデータからファイルを作り直すため、手で書いたコメントや元のキー順は残りません。残したい内容はあとで .bak ファイルから移してください。

リポジトリ形式 0 から 1 へ

リポジトリ形式は manifest のバージョンとは別物です。manifest の構造ではなく、artifact をディスク上にどう配置するかをバージョン管理し、manifest.jsonc の repositoryFormat に記録されます。現在の形式は 1 で、このフィールドが無い場合は形式 0 を意味します。

形式 0 では、トラッキング対象のシンボリックリンクを profiles/ 配下に実際のシンボリックリンクとして保存していました。形式 1 では、POSIX 形式のリンク先を保持する通常の <name>.dotweave.symlink メタデータファイルとして保存するので、git を通してプラットフォーム間を移動できます。マイグレーションは profiles/ 配下をすべてたどり、見つけた物理的なシンボリックリンクを変換します。冪等なので、物理的なシンボリックリンクが残っていなければ再実行しても何も起きません。

設定のマイグレーションと違い、こちらはファイルシステムに触れます。そのため dry run ではない dotweave push のときだけ実行されます。dotweave push --dry-run はスキップします。dotweave track と dotweave untrack は、行っていないアップグレードを主張しないよう、既存の形式マーカーをそのまま書き戻します。つまりリポジトリを先へ進める手段は、実際の dotweave push を 1 回実行することです。

新しい dotweave のバージョンで最初に push する前に、同期ディレクトリをコミットしてクリーンな状態にしてください。形式のマイグレーションは profiles/ 配下のファイルを書き直すので、作業ツリーがクリーンならその書き直しを 1 つの git diff としてレビューできます。

リポジトリが新しすぎる、または古すぎるとき

dotweave は設定を読み込むたびにリポジトリ形式を確認します。そのため、理解できないリポジトリを半分だけ読むのではなく、コマンドがすぐに失敗します。

Repository format <n> is newer than this CLI supports は、別のマシンがすでにリポジトリをマイグレーション済みであることを示します。このマシンの dotweave をアップグレードしてください。dotweave はリポジトリを古い形式へ戻しません。

逆のケースは、この CLI が対応する最も古い形式より下のリポジトリです。古い dotweave リリースを用意し、そこで dotweave push を 1 回実行してリポジトリを先へ進めてから、あらためてアップグレードしてください。リリース済みの形式でこの下限を下回るものは無いため、この失敗は現時点では発生しません。将来、形式 0 の対応を落とすリリースのために用意された検査です。

実装とリファレンス

version、repositoryFormat、profiles の各フィールドの型と既定値は manifest.jsonc、グローバル設定のフィールドは settings.jsonc にまとめています。形式のマイグレーションが書き直す artifact の配置はディレクトリとリポジトリの構造で説明しています。

マイグレーション失敗時の正確な文言はエラーメッセージのリポジトリ形式の節を参照し、アップグレード後もコマンドが失敗する場合は同期の問題を解決するへ進んでください。