セットアップスクリプトはGit Worktreesをサポートすべき
Setup Script Should Support Git Worktrees (piechowski.io)
要約
この記事は、開発者が複数のGit worktreeを使用する際に発生する環境設定の課題について論じています。特に、複数のworktreeが同じポート、データベース、キャッシュキーなどを共有しようとすると競合が発生する問題を取り上げ、これを解決するために、各worktreeに一意のIDを割り当て、ポートやリソース名を動的に管理するセットアップスクリプトの重要性を強調しています。
全文翻訳
Your Setup Script Should Support Git Worktrees
worktree対応のセットアップスクリプトは、不足しているツールを診断し、単一のDockerスタックを共有し、安全な並行開発のためにポート、データベース、状態を分離できます。
Ally Piechowski · 2026年7月28日 · 5 分で読めます
[画像: Your Setup Script Should Support Git Worktrees]
私が関わっているある本番アプリケーションでは、新しいGit worktreeは単一のセットアップスクリプトで実行可能になります。
bin/setup
Setupは環境を準備して終了し、その後通常の開発コマンドが実行されます。ここではリポジトリが既に使っているコマンドのショートハンドとしてbin/devを使用します。Setupはサーバーを巧妙なプロセス管理ツールの中に隠しません。
bin/setupはリポジトリ所有の実行可能ファイルで、チェックアウトを動作する開発環境に変換します。プロジェクトに合わせてmake setupやscript/bootstrapと呼んでも構いません。インターフェースは名前よりも重要です。単一のコマンドは、準備完了のリポジトリか、正確な修復手順のいずれかを返します。
同じコマンドは、すべてのGit worktreeから機能するはずです。並行コーディングエージェントは、これを通常の開発インフラストラクチャとして扱うほど重要にしました。
2つ目のチェックアウトは2つ目の環境ではない
Git worktreeは、リポジトリの共通Gitデータを共有しながら、独自のワーキングツリー、HEAD、インデックスを持つ別のチェックアウトです。この分離はコードにとって素晴らしいものです。Gitは、アプリケーションの2つのコピーが同じポート、データベース、キャッシュキー、コールバックURL、Terraform状態、またはコンテナ名を必要としていることを認識しません。
これは2つのworktreeを実行しようとすると問題になります。
git worktree add ../app-payment-fix -b payment-fix
cd ../app-payment-fix
bin/setup
bin/dev
単一の永続的なクローン用に書かれたセットアップスクリプトは、同じ.envをコピーし、すべてのチェックアウトを同じデータベースに向けさせることができます。2つのworktreeが起動すると、それらの開発サーバーはホストポートを奪い合う可能性があります。Composeプロジェクトも、プロジェクト名や固定コンテナ、ネットワーク、ボリューム名を再利用すると重複し、公開ポートは依然として衝突します。2つ目のworktreeは起動に失敗するか、静かに状態を共有します。
Worktreeはコーディングエージェントよりもずっと前から存在していました。最近では、このアプリケーションで複数のアクティブなチェックアウトを持つことがよくあります。Gitはそれらのファイルを分離して保持します。Setupは依然としてポート、データベース、ローカル状態を分離する必要があります。
worktreeごとに完全なDockerスタックを実行するのは理解しやすいですが、データベースやその他のローカルサービスが重複します。このアプリケーションでは、単一のスタックを共有し、各worktreeに独自のポート、データベース名、リソース名を与えています。
| マシンごとに一度共有 |
| --- | --- |
| データベースおよびキャッシュサーバー |
| ローカルサービスコンテナ |
| パッケージダウンロードおよびツールキャッシュ |
| worktreeごとに分離 |
| --- | --- |
| 開発用およびテスト用データベース名、キャッシュ名前空間 |
| キュー名、バケット、コールバックURL、インフラリソース名 |
| アプリケーションポート、環境ファイル、ログ、PID、ローカル状態 |
セットアップスクリプトは、読みやすいworktree IDを導き出し、それを小さなローカルレジストリと比較し、生成された設定を書き込みます。
WORKTREE_ID=<derived-worktree-id>
APP_PORT=<allocated-port>
DATABASE_NAME=app_dev_<worktree-id>
TEST_DATABASE_NAME=app_test_<worktree-id>
レジストリの割り当てにはロックが必要です。なぜなら、エージェントが同時にセットアップを開始できるからです。ロックは、それを尊重するセットアッププロセスのみをシリアライズします。堅牢なアロケーターは、古い予約を削除し、候補ポートを選択し、現在のリスナーをチェックしてから、IDをアトミックにコミットする必要があります。
そのリスナーチェックはスナップショットにすぎません。開発コマンドは、後でバインド衝突を明確に報告する必要があります。スクリプトは再実行可能であっても、同時実行下では失敗する可能性があります。冪等性だけでは不十分です。
bin/setupが担当するもの
Setupは、git worktree addと通常の開発コマンドの間のすべてのステップを担当します。
- リポジトリで宣言されたツールチェーン(私はmiseを使用)をブートストラップします。
bin/doctorを実行して、残りのホスト要件を診断し、必要に応じて正確な修復手順で停止します。- 共有Dockerサービスが実行中で正常であることを確認します。
- worktreeのIDとポートを割り当てるか、回復します。
- ローカル環境およびサービス設定を生成します。
- 分離された開発用およびテスト用データベースを作成および移行します。
- アプリケーションが依存関係に到達できることを確認してから終了します。
そのブートストラップはmiseである必要はありません。私はmiseを使用して、言語ランタイム、パッケージマネージャー、および小さなCLIツールをリポジトリにピン留めします。Setupは、不足している設定済みバージョンに対してmise installを実行できます。Git、Docker、オペレーティングシステムライブラリ、および認証情報は依然として必要になる場合があります。
リポジトリがmiseを使用している場合、ツールのインストールはすべてのシェルでアクティブになりません。Setupは、リポジトリコマンドをmise exec -- ...経由で実行するか、明示的にシェルアクティベーションを要求する必要があるため、偶発的なシェル設定が結果を変更することはありません。
これにより初回コミットまでの時間が短縮されますが、オンボーディングはその最初のメリットにすぎません。同じパスが、人間またはエージェントがworktreeを開くたびに実行されます。
Setupを早期に失敗させる
bin/doctorはセットアップの早い段階に配置されるべきであり、独立して実行することもできます。追加する前は、セットアップがffmpegが不足していることを発見する前にシードステップに到達する可能性がありました。Doctorは現在、高価な作業が始まる前にそれをキャッチします。
有用なDoctorは、すべての要件をチェックし、すべての失敗を収集し、非ゼロで終了し、人が貼り付けられる修復手順を出力します。
FAIL container engine: daemon not reachable
Start Docker, then run bin/doctor again.
FAIL tools: configured versions are missing
Run: mise install
Doctorは、安定した終了コード、プロンプトなし、ターミナルまたはエージェントのトランスクリプトで機能する出力で、すべてのリストを一度に報告するべきです。
共有データベースの再起動は、すべてのworktreeを中断します。互換性のないサービスバージョンを必要とするブランチは、同じスタックを使用できません。キャッシュキー、メールボックス、キュー、オブジェクト名は、セットアップがworktree IDでそれらをプレフィックスしない限り、依然としてクロスウォークします。
一部の作業には、より強力な分離が必要です。破壊的な移行作業、サーバー全体をリセットするテスト、またはデータベースエンジンをアップグレードするブランチは、専用のスタックに値するかもしれません。共有スタックは、ルールではなく、高速なデフォルトです。
リセットおよびテイクダウンコマンドも同様の境界が必要です。git worktree removeはアプリケーションのクリーンアップを呼び出さないため、リポジトリ所有のbin/teardownはポートを解放し、そのworktreeのデータベースのみをドロップし、その生成された状態のみを削除する必要があります。通常のbin/resetは、共有ボリュームや他のチェックアウトのリソースを消去してはなりません。マシン全体のリセットは明示的に行い、誤って実行するのが困難になるようにしてください。
受け入れテストは、コピーされた環境ファイルがないクリーンなworktreeから開始します。単一のworktreeでセットアップを2回実行し、次に2つのworktreeで同時に実行します。両方の開発サーバーを起動し、両方のテストスイートを実行し、一方のworktreeをテイクダウンし、もう一方が実行し続けることを確認します。そこで見つかったすべての手動修正は、bin/setupまたはbin/doctorに属します。