作品フォルダとGitで管理する

11.1 sb3-toolchainで作品と拡張を管理する

sb3-toolchainは手元で使うNode.jsのツールです。importでSB3を作品データ・素材・埋め込み拡張に展開し、Gitで変更を確認できます。checkで展開したデータを検証し、buildで配布用のSB3を生成します。展開した作品フォルダは、エディターで直接開いて編集することもできます（「作品フォルダを開いて保存する」）。

• 拡張のメタデータを管理する。拡張コードのヘッダーに書いた名前、説明、サンドボックスの要件をバンドル時に読み取ります。GitHubのコミットやnpmのバージョンを固定し、埋め込むコードのSHA-256を検証できます。更新時はAPIマニフェストを使って互換性を調べることもできます。
• 複数の拡張を1つにまとめる。元のコードを残したまま、配布するSB3に複数の拡張を1つの複合拡張として埋め込めます。実行許可は複合拡張全体に対して判断します。
• 公式カタログの信頼条件を確認する。公開版のエディターでは、TurboWarp Plusファミリー公式カタログの条件を満たす拡張を信頼済みとして扱います。エディターはカタログに載っている取得元やコードのSHA-256を照合してから、個別の承認画面を省略します。

SB3の展開・再生成 · 拡張のバンドル · 公式カタログ

11.2 作品フォルダを開いて保存する

sb3-toolchain v1で展開した作品フォルダを、SB3にまとめ直さずに開いて保存できます。ブラウザーでフォルダを選んで書き込むには、File System Accessに対応したChromeやEdgeが必要です。

作品フォルダを作る

新規作品やSB3を開いているときは、画面左上の「プロジェクトフォルダ」ボタンでパネルを開き、「プロジェクトフォルダを作成」を押して保存先のフォルダを選びます。空でないフォルダを選ぶと、中身を上書きしてよいかを確かめる画面が出ます。作成が終わると、そのフォルダのファイルがパネルに表示され、以後の保存はそのフォルダに書き込みます。

作品フォルダを開く

「ファイル」→「プロジェクトフォルダを開く…」を選び、作品フォルダを選んで読み書きを許可します。作品データとローカルの画像・音声が読み込まれます。

作品フォルダに保存する

1. ブロック、変数・リスト、スプライトやコスチューム、スプライトの位置や大きさなどを編集します。作品を実行して変わった位置や変数の値も保存の対象です。
2. 「ファイル」→「プロジェクトを保存」を選ぶと、フォルダ内のproject.source.jsonが更新されます。保存前に、フォルダが外部で変更されていないかを確かめます。

スプライトの追加・削除・名前の変更と、コスチューム・音の追加・削除も保存します。このとき、フォルダ内のassets/とsb3-source.jsonも更新し、使われなくなった画像・音声のファイルを消します。システムフォントとWebフォントの参照は作品データに、ファイルのフォントはassets/に保存します。

埋め込み拡張や、URLで読み込むカスタム拡張を含む作品も開いて保存できます。拡張のコードはextensions/とembedded-extensions.jsonに書き戻します。拡張を差し替えて出どころの記録（source）が外れたときは、保存時に知らせます。

フォルダが外で変わったとき

作品フォルダを開いている間、エディターはフォルダが外で変わっていないかを確かめ続けます。コーディングエージェントやテキストエディターがファイルを書き換えたり、Gitでブランチを切り替えたりpullしたりしてファイルが変わると、画面の右下に「外部変更あり」が出ます。

未保存の編集があるときにフォルダが変わると、どちらかを捨てることになります。ほかの道具でブランチを切り替えたりpullしたりする前に、エディターで保存して作品を止めておきます。外で変わったフォルダに保存しようとすると、上書きは止まり、編集はエディターに残ります。

作品フォルダのファイルとGit状態を見る

画面左上の「プロジェクトフォルダ」ボタンで「作品フォルダ」パネルを開きます。ファイル名の下には、作品データ、コスチュームと音、拡張など、ファイルの用途が表示されます。

• *はエディターで編集中の内容が未保存であることを示します。ファイル名の後ろに半角スペースを空けて表示し、保存すると消えます。
• 太字は、最新コミット（HEAD）と比べて保存済みの内容が変わったファイルや、Gitに追加してまだコミットしていない新しいファイルを示します。
• ✨は、保存済みでGitがまだ追跡していないファイルです。
• 打ち消し線は、最新コミットにあったファイルが削除されたことを示します。削除したファイルは元のフォルダ内に表示されます。
• 保存した内容が最新コミットと一致するファイルは、名前が青になります。現在のブランチの追跡先ブランチ（GitHub上の対応するブランチ）にも同じ版があれば紫、GitHubのPRのマージ結果に同じ版が入ったことを確認できれば緑になります。

保存済みの内容に変更があり、その上で編集を続けている間は、太字のファイル名に*が付きます。コミットすると、その内容と一致するファイルは通常の太さに戻ります。

ポインターをファイル名に合わせると、状態が文字で表示されます。変更箇所を見るには、ファイルを開いて「差分」に切り替えるか、ローカルGitで対象のファイルを選びます。画像・音声・動画はプレビューで開きます。

パネル右上のボタンで、ファイルの検索、ドロワーの固定、別ウィンドウへの切り離しができます。斜線付きのピンは固定を解除した状態です。ファイルやフォルダを右クリックして操作したり、ドラッグして別のフォルダへ移したりもできます。作品が参照する素材や作品フォルダの管理ファイルは、作品の編集画面と保存操作で更新します。

SB3を作品フォルダに展開するコマンドProject Starterも使えます（Project StarterでScratch作品を移す）。

作品フォルダの編集 · フォルダの差分再読み込み

11.3 ローカルGitで変更と履歴を確かめる

「ファイル」→「リポジトリを選択…」で、.gitを持つリポジトリのルートを選びます。メニューバー右側の「ステージを開く」の左にあるボタンからも操作できます。リポジトリを選ぶ前は「Git ▾」と表示され、「リポジトリを選択…」と「ローカル Git を開く」を選べます。リポジトリを選ぶと、ボタンには現在のブランチ名が表示され、ブランチの切り替え、「新しいブランチ…」、「ローカル Git を開く」を選べます。

「ファイル」→「リリース…」の使い方はリリースして配るで説明しています。

1リポジトリに1作品を基本にします。リポジトリの直下、またはProject Starterが作るproject/に作品があり、まだ開いていなければ、ローカルGitの上部に「作品を開く」が表示されます。ほかの場所にある作品は「ファイル」→「プロジェクトフォルダを開く…」で開くと、選択中のリポジトリに関連付けられます。作品を開くと、ステージやスプライトごとに変更を確認できます。リポジトリの構成

ローカルGitの先頭行には「リポジトリ: 名前」が表示されます。その横の「ローカル状態を更新」はGitの状態を読み直します。エディターの外でGitを操作したら、これを押します。GitHub接続付きのエディターでは、ここに「GitHub に接続…」も表示されます。エディターでブランチを切り替えたりpullしたりすると、結果の表示に「作品を再読込」が出ます。これを押すと、その版の作品を開き直します。左に「作品フォルダ」パネルを表示している間は、フォルダのアイコンが付いた「ローカル Git」タブがタブ列の左端に固定されます。

その下の「ファイルの保存」「保存のコミット」「PRを作成」「マージ」で表示を切り替えます。「ファイルの保存」と「保存のコミット」には対象のファイル数が表示されます。

• ファイルの保存では、左の一覧でファイル名を選ぶと、現在のブランチの最新コミット（HEAD）と未保存の編集内容の差分が右に表示されます。作品のコードはブロックで比べられます。「未保存のファイルを保存」を押すと、編集内容を作品フォルダに書き込みます。
• 保存のコミットでは、保存した内容をHEADと比べます。追加したファイルや削除したファイルも表示されます。変更のあったステージやスプライトが左の一覧の上部に並び、READMEなどは「その他のファイル」に表示されます。コード以外の変更は「そのほかの設定」などの項目に分かれます。項目やファイル名を押すと、右に差分が出ます。作品データや素材をファイル単位で選ぶには「ファイル単位の一覧」を開きます。左下のコミット欄は一覧をスクロールしても表示されたままで、選択件数を確かめてコミットメッセージを入力できます（保存からコミットまで）。

「PRを作成」では、「コミットの履歴」と「ローカルブランチ」を確認し、コミットを選んで変更を見られます。ブランチの切り替えと作成もここで行います。「GitHub に送ることを許可する（push）」を付けてGitHubに接続していれば、反映先を選んでPRを作れます。「マージ」では「PR一覧」から対象を選び、差分やマージの状態を確かめます。

画面左上の「Git 履歴」ボタンでは、選択中のリポジトリのコミットを一覧できます。コミットを選ぶと「ローカル Git」の「PRを作成」が開き、そのコミットの変更が一覧に出ます。ステージ・スプライトやファイルを選ぶと差分を確認できます。

コミットの「⋯」からは、「この版を開く」「ここからブランチを作る…」「コミットの ID をコピー」を選べます。作品フォルダを開いていれば、「この版を開く」で選んだ版を別のプレイヤーで実行できます。編集中の作品はそのまま残り、プレイヤーを閉じると戻れます。

起動URLにtwPlusGitRestoreVersion=1を指定すると、「⋯」に「この版に戻す…」が加わります。対象の作品ファイルと追加・変更・削除を確かめて「復元してコミット」を押すと、現在のブランチにローカルコミットができます。「作品を再読込」で復元した版を開けます。この機能は既定では無効です。

git worktreeで追加した作業ツリー、サブモジュール、シンボリックリンクは扱えません。作業ツリーの実行権限の変更はブラウザーからは確認できません。ローカルGitを使わない場合は起動URLにtwPlusLocalGit=0を指定します。このときメニューバーの「Git ▾」ボタンと「Git 履歴」ボタンも表示されません。

ローカルGitパネル

11.4 作品の変更をブロックで比べる

「保存のコミット」で対象のステージやスプライトの「コード」を選ぶと、作品データ（project.source.json）の差分をスクリプト単位で表示します。「テキスト」に切り替えると、JSONの行単位の差分を確認できます。

• 変更のあったスクリプトだけを比較項目にし、変更前と変更後のブロックを並べて表示します。追加・削除・入力値の変更などには注釈が付き、変更された入力欄やフィールドはオレンジの枠で示します。
• 「編集画面で強調」を選ぶと、つながったスクリプトの中で変更箇所を確認できます。
• 分割・結合したスクリプトも、両方の版に共通するブロックを手がかりに1つの項目にまとめます。
• 変数、リスト、コスチューム・背景、音、モニターなど、スクリプト以外の変更は別に示します。

黄色い縦横の帯とスクロールバーの目印で、変更箇所の位置が分かります。ポインターを帯の横位置や高さに合わせると、対応する帯が濃くなります。

エディターに定義がない拡張ブロックは、名前とつながりが分かる代替ブロックで示します。拡張のコードを取得したり実行したりはしません。

PRのスクリプト単位のレビュー

11.5 GitHubと同期する（fetch・pull・push）

メニューバー左端のPlusロゴから「GitHub 接続設定…」を開き、接続に使う既定の方式を選びます。設定はブラウザーに保存され、作品やリポジトリを開く前にも変更できます。変更は次の接続から使われ、接続中のセッションはそのまま続きます。

リポジトリごとの認証は、ローカルGitの先頭行にある「GitHub に接続…」で行います。接続先（選んだリポジトリのGitHub HTTPSリモートorigin）を確認して認証し、必要に応じてpushやPRレビューの送信を許可します。接続の確認と切断もここで行います。接続すると「PRを作成」と「マージ」に「GitHub と同期」の欄が表示され、pullとpushの対象となる現在のローカルブランチと、確認できた同期状況が並びます。

公開版（GitHub Pages）では、「GitHub 接続設定…」を開くと「GitHub 接続先が設定されていません。」と表示され、ローカルGitに「GitHub に接続…」は出ません。接続できない環境でも、外部のGitとGitHubの画面で同期とレビューを続けられます。接続がない場合の手順

接続方式を選ぶ

PATとcredential helperはclient IDなしで使うための方式です。Desktop本体と同梱のエディターの両方が対応している場合に選べます。同梱版は配布物のビルド情報で確認できます。Desktopの固定リビジョン · エディター側の対応

GitHub Appをインストールして認可する

1. 運用者から案内されたGitHub Appのページで「Install」を押します。インストール先のアカウントを選び、組織で必要な場合は管理者に承認を依頼します。
2. 「Only select repositories」でエディターから使うリポジトリを選びます。同期にはContentsの権限、レビュー送信にはPull requestsの書き込み権限も確認します。
3. ローカルGitの「GitHub に接続…」で、対象リポジトリと必要な許可を確認します。GitHubの認可画面ではApp名と権限を確かめます。Desktopの場合は、自分のエディターに表示されたデバイスコードだけを入力します。
4. 利用を終えたらエディターで接続を切ります。GitHubの「Settings」→「Applications」で、インストールは「Installed GitHub Apps」、認可は「Authorized GitHub Apps」から取り消せます。

Appに権限が追加されたときは、「Installed GitHub Apps」でインストール先の承認を済ませます。GitHub AppのトークンはCloudflareのサーバーまたはDesktopのメインプロセスが保持します。エディターのGitパネルは、対象リポジトリと操作を限定した短時間のプロキシ用の鍵で通信します。接続先運用者向けのGitHub App設定

接続したリポジトリを同期する

• fetch。「リモートの情報を更新（fetch）」で、リモートのブランチとコミットを取得します。
• pull。作品の実行を止め、未保存の編集と作業ツリーの変更を片づけてから「手元のブランチとファイルを更新（pull）」を押します。fast-forwardできる場合に取り込み、「作品を再読込」で開き直せます。
• push。接続時にpushを許可し、「現在のブランチを送る（push）」を押します。結果が不明なら、再送する前にfetchでリモートのブランチを確かめます。

GitHubに送る手順 · 接続の統合検証

11.6 プルリクエストをスクリプト単位でレビューする

GitHubのプルリクエスト（PR）を、変更全体の概要から個々のスクリプトまで確認できます。図版は、GitHub接続のない公開版の「マージ」で公開PRを開いた例です。turbowarp-kamishibai-appのPR #219

1. PRを選ぶ。対象リポジトリを選んで「マージ」を開き、左の「PR一覧」から対象を選びます。一覧が長いときは「前のページ」「次のページ」で移動します。各行の状態ラベルで、マージ可能、競合あり、ドラフト、マージ済み、クローズ済みなどを確認できます。GitHub接続でCIの状態を取得できる場合は、その結果も表示されます。
2. 変更概要を確認する。右側の「概要」でPRの説明とマージ状況を確認します。「コミット」には対象のコミットが並び、「チェック」ではCIの状態と、取得できる場合はチェックごとの結果を確認できます。

   

3. コミットとチェックを見る。「コミット」にはメッセージ、作者、コミットIDが表示されます。「チェック」ではPRの先端コミットで実行されたチェックの結果を確認できます。

   

   

4. スクリプトをブロックで比較する。件数が付いた「変更ファイル」タブを開きます。上部の「変更レビュー」で、影響するステージ・スプライトの数、コードの変更の数、確認済みの数が分かります。project.source.json（この例ではapp/project.source.json）のカードで対象のステージやスプライトの見出しを探し、その下に並ぶスクリプトから、例の「緑の旗が押されたとき」を展開します。左の「変更前」と右の「変更後」を見比べ、枠で示されたブロックがスクリプトのどこにあるかを確かめます。長いスクリプトや横に広いブロックは、比較枠をスクロールして確認できます。比較枠にポインターを重ねると、右下にミニマップと拡大・縮小ボタンが表示されます。

   

比較を読み終えたら、スクリプトの比較枠の右下にある緑色の「確認済み」で進み具合を記録できます。この印はブラウザーに保存され、パネルを閉じてもエディターを再読み込みしても残ります。PRが更新されると、内容が変わったスクリプトの印だけが外れます。印は作品ファイルにもGitにも書き込まれません。手元の差分に戻るには「保存のコミット」を選びます。

比較の仕組み。比較にはPRのマージベースとheadを使います。未接続時は公開APIで公開PRを比較できます。接続中は許可された非公開リポジトリのPRも一覧から選べます。PRのheadとベースのブランチをGit Smart HTTPで取得して比較します。PRの反映先を取得できない場合は、GitHub側の既定ブランチを使います。候補が複数あるときは、比較先のブランチを選べます。ブロックでの表示のしかたは作品の変更をブロックで比べるで説明しています。

関連する操作。右ペインのPR番号とタイトルからGitHubのPRを開けます。PR見出しの右上にある「差分をエディタのタブで開く」アイコンを押すと、作品の差分がエディターの別タブで開きます。変更ファイルのカード右上にある「別ウィンドウで開く」を押すと、そのファイルのブロック差分を別ウィンドウで確認できます。エディターのタブや別ウィンドウで付けた「確認済み」は、ローカルGitの「変更ファイル」の表示にも反映されます。メニューバーのブランチのボタンは、手元で編集するブランチを切り替える操作です。

PRの版を実行するには、作品フォルダを開いておき、GitHubに接続した状態で開いたPRの「PRの作品を開いて動作確認」を選びます。比較したコミットにローカルブランチ（例：pr/219）を作って切り替え、その版の作品を開き直します。作品の実行中、未保存の編集や作業ツリーの変更があるとき、同名のブランチが別のコミットを指しているときは、切り替えずに止まります。確認を終えたら、メニューバーのブランチ名から元のブランチに切り替え、「作品を再読込」を選びます。確認用のブランチは手元に残ります。

レビューを送信する

「確認済み」は自分の確認状況を示す印です。GitHubにレビューを送信するには、接続時に「レビューの送信を許可する」を選んでから、PRを開きます。接続先でレビュー用GitHub APIが有効で、リポジトリでレビューを送れる権限が必要です。

「レビューを送る」で全体とコードへのコメントを確認し、結果に「コメント」「承認」「修正を依頼」のいずれかを選び、「レビューを送信」を押します。コードへのコメントをスレッドにできるか、本文に入るかは送信前の表示で確認できます。送信欄を使えない場合はGitHubのPRを開き、「Files changed」からレビューします。検査・レビュー・マージの手順

接続先の運用者はCloudflareのGIT_GITHUB_API、DesktopのTW_PLUS_DESKTOP_GIT_GITHUB_APIでAPIのグループを有効にします。review-threadsは差分の位置に付けるコメントを扱い、reviews-bodyは本文だけのレビュー送信に使えます。DesktopのAPIは既定で無効です。APIの設定 · レビュー送信の検証状況

エディターへの接続 · PRレビューの操作手順 · PRをScratchスクリプトでレビュー