コンテンツにスキップ

af-scratch

ビルドの生成物をワークスペースの作業ディスクへ移し、元の場所にシンボリックリンクを残します。作業ディスクがあるのは 一部の配備だけです。そこではホームディレクトリがネットワークストレージで、小さいファイルの多いツリーが遅く、作業ディスクは ローカルで速いディスクです。作業ディスクの中身は、ワークスペースを停止すると消えます。置くのは、ビルドで作り直せる 生成物だけにしてください。作業ディスクのないワークスペースでは、af-scratch は何もしません。

af-scratch とは別に、ワークスペースは起動時に Go のビルドキャッシュ、Go のモジュールキャッシュ、uv のキャッシュを 作業ディスクへ移します。作業ディスクが 30 GiB 以上あり、書き込めるときに限ります(30 GiB は既定値で、配備がこのしきい値と 対象を変えられます)。既定では node_modules と npm のキャッシュは何も移さず、.venv は自分で指定したときだけ移ります。

ターミナルウィンドウ
af-scratch <dir>...
af-scratch --status
af-scratch --auto [<root>]
af-scratch --repair
af-scratch --seed
形 動作
<dir>... ディレクトリをそれぞれ作業ディスクへ移し、シンボリックリンクに置き換えます。まだないディレクトリは、作業ディスクの移し先へのリンクになります
--status いま移しているものを、それぞれのサイズと一緒に出します
--auto [<root>] <root>(既定はいまのディレクトリ)の下のプロジェクトがこれから作る生成物を移します。ワークスペースが、クローンや作業コピーを新しく作るたびに実行します
--repair af-scratch の一覧にあるリンクのうち、停止でリンク先がなくなったものについて、作業ディスク側のディレクトリを AF_SCRATCH_REPAIR_MAX 個まで作り直します。ワークスペースが起動のたびに、セッションより先に実行します
--seed 一度エラーなしで探し終えるまで、一覧を持たない古い af-scratch が張ったリンクを探して一覧に加え、そのリンク先も作り直します。ワークスペースが起動時に、セッションより先に最長 AF_SCRATCH_SEED_TIMEOUT 秒実行し、残りはバックグラウンドで続けます

引数なしで実行すると、使いかたを表示して終了コード 1 で終わります。--help はありません。渡すとディレクトリ名として 扱われます。

ディレクトリは $AF_WS_SCRATCH/artifacts/ の下に、元の絶対パスのまま移ります。2 つのプロジェクトの target が ぶつかることはありません。

$ af-scratch target
af-scratch: target を作業ディスクへ移しています…
af-scratch: target -> /scratch/artifacts/home/dev/repos/shop/target(ワークスペース停止で消えます)

停止したあともリンクは残りますが、リンク先はなくなっています。ビルドはリンクの先を作ってくれません。Gradle は Failed to create parent directory で失敗し、Maven と cargo も同じようにリンク先のないリンクを受け付けません。 そこで af-scratch は、張ったリンクの一覧を ~/.local/state/af-scratch/links に残します。ワークスペースは起動のたびに、 セッションが動き出す前に af-scratch --repair を実行して、それぞれのリンク先を空のディレクトリとして作り直します。 リンク先のないリンクに af-scratch target や --auto を実行したときも作り直します。リンク自体がなくなった項目は、 次の起動で一覧から消えます。

作り直すのは、リンク先が $AF_WS_SCRATCH/artifacts/ の下にあり、その下の途中にシンボリックリンク、..、ファイル、 改行がないときだけです。パスに改行を含むディレクトリは、リンク先を作り直せないので、af-scratch は移しません。ほかの場所を指すリンクはあなたが張ったものなので、af-scratch はその先に何も作りません。 断ったパスは起動時のログに出ます。

次のリンクは起動後もリンク先がないままです。手で af-scratch <dir>(または af-scratch --repair)を実行してください。

  • パスに改行を含み、古い af-scratch が張ったリンク。一覧に載っていません
  • 作り直せるリンク先のないリンクが AF_SCRATCH_REPAIR_MAX(既定 500)より多いとき、または一覧の項目が AF_SCRATCH_REPAIR_SCAN(既定 5000)より多いときの残り。一覧には残り、起動時のログに数が出て、次の --repair が 続きを処理します。作業ディスクの外を指すリンクは一覧から消え、数に入りません
  • 一覧ができる前に張られたリンクで、--seed がまだたどり着いていないか、見つけられないもの(下を参照してください)
ディレクトリの状態 動作
すでにシンボリックリンク 何もしません。リンク先を表示します。リンク先が $AF_WS_SCRATCH/artifacts/ の下にあって存在しなければ、空のディレクトリとして作り直します
ある 作業ディスクへ移してからリンクします。この 1 回は、ホームディレクトリから全部を読むので遅くなります。作業ディスクの移し先にすでにあったものは、先に削除します
ない 作業ディスクの移し先にリンクします。移し先がなければ空で作ります。あれば(停止前の移動の残りなど)、中身ごとそのまま使います
名前が node_modules 断ります。npm は次のインストールでリンクの node_modules を実体のディレクトリに置き換え、npm ci はその前に作業ディスク側を空にします
名前が .venv 警告を出して移します。uv venv と uv sync はリンク越しに使えますが、python3 -m venv .venv は失敗します

af-scratch は、指定したものを git が追跡しているかどうかを確かめません。追跡しているファイルや未コミットの作業は 指定しないでください。停止で消えます。

<root> の下 3 階層まででプロジェクトのファイルを探します。.git、node_modules、.venv、target、build、 dist の中には入りません。

プロジェクトのファイル 移すディレクトリ
Cargo.toml、pom.xml 隣の target
build.gradle、build.gradle.kts 隣の build

それぞれのディレクトリについて、手で移すときより厳しい規則に従います。

  • シンボリックリンクには触りません(ほかの作業コピーと共有するために、自分で張ったリンクかもしれないため)。 ただし、$AF_WS_SCRATCH/artifacts/ の下を指していてリンク先がないものは、リンク先を作り直します
  • すでにあって、git が無視していないディレクトリには触りません
  • すでにあって、git が無視しているディレクトリは、移してリンクします
  • ないディレクトリは、新しい空のディレクトリにリンクします。最初のビルドから作業ディスクに書き込まれます

そのため、新しいチェックアウトには空の target や build のリンクがあります。[ -d build ] || … のような確認は これをビルド済みと見なすので、ビルドは条件を付けずに実行してください。

--auto が node_modules と .venv を移すことはありません。作業ディスクがなければ、--auto、--repair、--seed は何もせずに終わります。終了コードはいつも 0 です。

--repair は一覧だけを読みます。起動時の手間はリンクごとの確認だけで、~/repos を見て回ることはありません。 一覧への書き込みはロックを取るので、同時に動いた --auto の記録が消えたり、二重に載ったりすることはありません。 --repair がリンクを読み切れなかったときは一覧をそのまま残し、起動時のログにそう出して、次の起動でもう一度試します。

--seed は、一覧ができる前に張られたリンクのためのものです。~/repos の下を AF_WS_SCRATCH_AUTO_DEPTH + 1 階層まで (そこにあるクローンに --auto が使う深さです)探して target と build のシンボリックリンクを見つけ、 $AF_WS_SCRATCH/artifacts/ の下を指すものを一覧に加えてリンク先を作り直します。最後までエラーなしで探し終えたときだけ ~/.local/state/af-scratch/seeded を残し、次からの起動では何もしません。読めないディレクトリがあったり、記録に 失敗したりしたときは印を残さず、次の起動でもう一度探します。起動時は最長 AF_SCRATCH_SEED_TIMEOUT 秒(既定 20 秒) 待ち、残りはバックグラウンドで続けます。そのためその起動に限り、まだたどり着いていないリンクはしばらくリンク先がないままのことが あります。一覧ができる前に、それより深い場所へ手で張ったリンクは見つかりません。そのリンクに一度 af-scratch <dir> を実行してください。

$ af-scratch --status
/home/dev/repos/shop/target 412M
/home/dev/repos/app/build 96M

元のパスがまだシンボリックリンクであるディレクトリを出します。対象は、元のパスが / から数えて 6 階層までのものです (/home/dev/repos/shop/app/target が 6 階層)。一度も移していなければ 逃がしているものはありません。 と出ます。 移したことはあってもリンクが 1 つも残っていなければ、何も出ません。

変数 効果
AF_WS_SCRATCH 作業ディスク。配備が設定します。設定されていなければ、af-scratch は何もしません
AF_WS_SCRATCH_AUTO=0 --auto を止めます
AF_WS_SCRATCH_AUTO_DEPTH --auto が <root> の下を何階層まで探すか。既定は 3 です。--seed は ~/repos の下を 1 階層深く探します
AF_SCRATCH_REPAIR_MAX 1 回の --repair で作り直すリンクの数の上限。既定は 500 です
AF_SCRATCH_REPAIR_SCAN 1 回の --repair で確かめる一覧の項目数の上限。既定は 5000 です
AF_SCRATCH_SEED_TIMEOUT 起動時に --seed を待つ秒数。過ぎるとバックグラウンドで続けます。既定は 20 秒です
値 意味
0 完了。--auto、--repair、--seed はいつもこれです
1 作業ディスクがない(AF_WS_SCRATCH が設定されていない)、引数がない、または node_modules を指定した(ほかに指定したディレクトリは処理します)。移動やリンクに失敗したときもこれで、シェルのエラーを表示し、それ以降は処理しません
  • ワークスペースを作り直す:停止、作り直し、ホームディレクトリの掃除で何が残るか
  • af-db:af-db up --ephemeral はデータベースを作業ディスクに置きます