gh-stackx

gh-stackx

プライベートプレビュー版の GitHub Stacked PRs API が利用できないリポジトリで、スタックされたプルリクエストを管理するには、gh-stackx gh 拡張機能を使用します。

使用する場面

• 依存関係のある一連の PR を開きたい場合。
• gh stack submit が ⚠ Stacked PRs are not enabled for this repository で失敗する場合。
• スタックのリベースまたはマージ後も、PR のベースを正しく保つ必要がある場合。
• PR のベースを手動で編集せずに、スタックを上から順にマージしたい場合。

セキュリティに関する注意

gh-stackx は、github/gh-stack gh CLI 拡張機能を使いやすくするためのラッパーです。ユーザーが設定した gh 認証情報を使って、ローカルで実行されます。このスキルが GitHub の認証情報を収集、保存、転送することはなく、拡張機能やその他のスキルを自動的にインストールすることもありません。インストールする前に、必ず gh 拡張機能のソースを確認してください。

前提条件

• gh CLI がインストールされ、認証済みであること。
• ローカルでのスタック操作用に github/gh-stack 拡張機能がインストールされていること。
• gh-stackx 拡張機能がインストールされていること。

gh extension install を自動的に実行しないでください。インストールは明示的に行う必要があります。また、gh の認証情報を付与する前に、ソースリポジトリ（github/gh-stack と ThePlenkov/gh-stackx）を確認してください。インストール手順については、リポジトリの README を参照してください。

基本概念

• トランク — ベースブランチ。通常は main です。
• スタック — 各ブランチが直前のブランチを基に構築される、順序付きブランチのリストです。
• ボトム — トランクに最も近いブランチです。
• トップ — トランクから最も遠いブランチです。
• ベース — PR の親ブランチです。最下層ではトランクを使い、それ以外の各層では直前のブランチを使います。

ワークフロー

スタックを作成する

git checkout main
git pull origin main

gh stackx init feature/auth
# work and commit

gh stackx add feature/api
# work and commit

gh stackx add feature/ui
# work and commit

PR を送信する

gh stackx submit       # drafts
gh stackx submit --open

submit はすべてのブランチをプッシュし、正しい --base と --head を指定して、下から上の順に PR を作成または更新します。各 PR の本文には、スタック全体をトップからトランクまで示す ## Stack GFM テーブルが含まれます。

トランクまたは親 PR の変更後に同期する

gh stackx sync
gh stackx sync --remote upstream

sync は gh stack sync を実行してから、gh pr edit --base で開いているすべての PR のベースを更新します。

上から順にマージする

gh stackx merge
gh stackx merge --squash
gh stackx merge --rebase

merge はスタックのトップから開始し、gh pr merge で開いている各 PR をマージします。

ローカルでの移動

以下のコマンドは github/gh-stack に渡されます。

gh stackx view --json
gh stackx up
gh stackx down
gh stackx top
gh stackx bottom
gh stackx trunk

gh-stackx は manifest.yml からリポジトリ情報とバージョンを取得して表示します。

gh stackx --version
gh stackx version
gh stackx -v

重要なルール

• sync または merge の前に、作業ツリーをクリーンな状態にしてください。未コミットの変更があると、リベース操作は失敗します。
• 子 PR を開く前に各ベースが存在するよう、下から上の順に PR を作成してください。
• 依存する PR を先にマージしてから親ブランチを移動できるよう、上から順にマージしてください。
• .git/gh-stack をコミットしないでください。これはローカルメタデータです。

トラブルシューティング

• gh stackx view が失敗する場合：github/gh-stack がインストールされていることを確認してください。
• PR のベースが間違っている場合：gh stackx sync を実行してください。
• submit または merge がエラーで停止する場合：根本原因となっている gh pr の問題を修正してから、再実行してください。

参考資料

ワークフロー全体は上記に記載されています。詳しくは、リポジトリ内の以下の資料を参照してください。

• 使用ガイド — 実例を使った実践的な手順です。
• スタックされた PR の手法 — スタックされた PR の仕組みと、その理由を説明します。
• 仕様書 — コマンドとアーキテクチャの完全な仕様です。
• REVIEW.md — このリポジトリのレビュー方針です。
• AGENTS.md — このリポジトリでの作業方法です。