仕組み

内部の仕組みを理解すると、dotweaveの動作が予測しやすくなります。 このガイドでは、メンタルモデル、pushとpullのデータフロー、そして 設計上の判断について説明します。

メンタルモデル

dotweaveは、ローカルの設定ファイルとGitで管理されるsyncディレクトリの間の 双方向ミラーと考えてください：

• 作業中はローカルファイルが正規データです。
• syncディレクトリはミラーで、Gitリモートにpushして別のマシンで pullできます。

dotweaveはファイルを勝手に変更しません — pushでミラーを更新するか、pullで ミラーからの変更を適用するか、明示的に実行します。

データフロー

エディタ → ローカルファイル → dotweave push → syncディレクトリ → git push → リモート
                                                                          ↓
別のマシン ← dotweave pull ← syncディレクトリ ← git pull ← リモート

2つの独立した操作があります。Gitによる転送はその間に位置しますが、 すべて自分でコントロールします。

pushフロー

1. manifest.jsoncを読み込む — dotweaveが設定ファイルを読み取り、 すべてのトラッキングファイルとその設定を把握します。

2. ローカルファイルを走査する — 各エントリについて、現在のプラットフォームの 解決済みlocalPathにあるファイルを読み取ります。

3. 既存のアーティファクトと比較する — syncディレクトリのファイルがすでに 同一であれば、何も書き込みません。

4. シークレットを暗号化する — secretとマークされたエントリは、書き込み前に ageで暗号化されます。

5. アーティファクトを書き込む — （暗号化されている場合もある）内容が syncディレクトリ内のrepoPathに書き込まれます。

pullフロー

1. manifest.jsoncを読み込む — 同じ設定ファイル、同じ解決ロジックです。

2. アーティファクトを読み取る — dotweaveがsyncディレクトリから各ファイルを 読み取ります。

3. シークレットを復号する — 暗号化されたファイルはローカルのageキーで 復号されます。

4. ローカルパスに書き込む — 内容が解決済みのlocalPathに書き込まれます。

5. パーミッションを適用する — 設定ファイルに記録されたファイルパーミッションが 復元され、意図せずファイルが誰でも読める状態になることを防ぎます。

ノート

pushもpullもGitのcommitを作成しません。git add、git commit、 git pushは自分で実行します。これにより、commit履歴を完全にコントロールできます。

設計上の判断

ローカルファースト

エディタはディスク上の実際のファイルに書き込み、dotweaveはそのファイルを読み取ります。 データベースもデーモンもバックグラウンドウォッチャーもありません。同期のタイミングは 自分で決めます。

シンボリックリンクなし

一部のdotfileマネージャーは、設定ファイルをリポジトリへのシンボリックリンクに 置き換えます。dotweaveは意図的にファイルをコピーします。これにより、パーミッションの 問題、ファイルシステム間の問題、シンボリックリンクを辿らないツールによる想定外の動作を 回避します。

age暗号化

シークレットはsyncディレクトリ内でageを 使って保存時に暗号化されます。ageはそのシンプルさから選ばれました — 単一のキーファイル、 キーサーバー不要、有効期限管理不要。プライベートキーがマシンの外に出ることはありません。

Gitをトランスポートとして活用

dotweaveは独自の同期プロトコルを発明するのではなく、Gitに乗っかっています。 ブランチ、履歴、マージコンフリクトツール、そしてホスティング（GitHub、GitLabなど）が そのまま使えます。

syncディレクトリの構造

syncディレクトリは予測可能なレイアウトの通常のGitリポジトリです。 詳細についてはディレクトリ構造ガイドをご覧ください。

概要：

~/dotfiles/          ← syncディレクトリのルート（Gitリポジトリ）
├── manifest.jsonc   ← トラッキングファイル一覧の設定ファイル
├── .age-key         ← ageプライベートキー（git-ignored）
├── .age-recipients  ← 暗号化用のage公開鍵
└── ...              ← dotweave pushで書き込まれるアーティファクト

ヒント

syncディレクトリを直接確認・管理したいときは、dotweave cdで移動できます。