Gitに変更を残さない仕組み
Skulはファイルを作成するときに、.gitignoreやGitの履歴、インデックスを変更しません。これを実現するのが、次の3つの仕組みです。
キャッシュとレジストリ
| パス | 保存する内容 |
|---|---|
~/.skul/library/ | すべてのプロジェクトで再利用するバンドルのクローン |
~/.skul/registry.json | 各リポジトリに適用したい構成と、各ワークツリーに実際に書き込んだ内容 |
適用したい構成と実際の書き込み状態は、別々に記録します。新しくリンクしたワークツリーは適用したい構成をすぐに引き継ぎ、skul applyを実行するとファイルが書き込まれます。
.gitignoreではなくローカルの除外ルール
Skulが作成するファイルは、.git/info/excludeに登録します。このルールはローカルのクローンだけに適用され、コミットもプッシュもしません。バンドルを削除すると、登録した項目も削除されます。
Skulは書き込んだすべてのファイルのフィンガープリントも記録します。管理対象のファイルを編集した場合は、削除前に確認を求めます。SKUL_NO_TUI=1の場合は処理を拒否し、編集内容を無断で失わないようにします。
ルートの指示ファイル
AGENTS.md、CLAUDE.md、QWEN.mdには別の扱いが必要です。チームがすでにこれらのファイルをコミットしている可能性があるためです。
自分の指示をローカルだけに適用するには、次の3点を守ってください。
- 変更を取り込むときは
skul syncを使います。それ以外のHEADを移動するGitコマンドは、実行前にskul shadow --suspendでシャドウを中断し、実行後に同じコマンドの--refreshで再適用します。 - Skulが管理している間は、ファイルを直接編集しないでください。
- 追跡中のファイルのシャドウを所有できるバンドルは、一度に1つだけです。
Gitが追跡していない場合
Skulはほかのファイルと同様にファイルを書き込み、Gitから隠します。ローカルにファイルがすでにあれば、その内容を元の状態として保存し、SKUL:BUNDLEマーカーで区切ってバンドルの内容を追記します。複数のバンドルで1つのファイルを共有でき、最後のバンドルを削除すると元のファイルに戻ります。
追記ではなく内容を置き換える場合は、--root-instruction-mode replaceを使います。この場合も、バンドルを削除すると元の内容が復元されます。
Gitが追跡している場合：シャドウ
Gitがすでに追跡しているファイルの差分は、除外ルールでは隠せません。そこでSkulは、HEADの内容に自分の指示を重ねたファイルを作業ディレクトリに書き込み、skip-worktreeを設定します。git statusには変更が表示されず、skul statusでは**シャドウ適用中の指示（Shadowed Instructions）**として表示されます。
追跡中のファイルのシャドウを所有できるバンドルは、一度に1つだけです。Skulは書き込んだファイルを生成物として扱うため、直接編集しないでください。Skulが書き込んだ内容と異なる場合、その後のコマンドは上書きを拒否します。
アップストリームの変更を取り込む
skip-worktreeはアップストリームの変更も隠します。そのため、HEADを移動する操作の前後でシャドウを中断し、再適用する必要があります。
skul sync
このコマンドはシャドウを中断し、git pull --ff-onlyを実行してから再適用します。pullに失敗した場合も、先にシャドウを復元します。アップストリームでファイルの追跡が終了していれば、そのシャドウを解除します。
ほかのGitコマンドは、同じ手順を手動で行います。
skul shadow --suspend
git rebase origin/main
skul shadow --refresh
ファイルにステージ済み、未ステージ、または未解決のマージによる変更がある場合、Skulはシャドウの作成や更新を拒否します。
後片付け
skul reset
このワークツリーでSkulが管理するものをすべて削除します。シャドウを適用したファイルはHEADの内容に戻し、保存していたローカルの元ファイルも復元します。git worktree removeの前に実行してください。実行しないと、存在しなくなったクローンの記録がレジストリに残ります。