gh-stack

gh-stack

gh stack は、スタック化されたブランチとプルリクエストのための GitHub CLI 拡張機能です。スタックはトランクを起点とする順序付きのブランチの連鎖です。各ブランチには、その下のブランチをベースとする PR が 1 つあり、レビュー担当者にはそのレイヤーの差分だけが表示されます。

gh stack は、トランクを先頭に左から右へスタックを表示します。

(main) <- auth <- api <- frontend

左が最下層、右が最上層です。auth は main をベースとし、最初にマージされます。frontend は最後にマージされます。up はトランクから離れて最上層へ進み、down はトランクに近づきます。基盤となる作業は最下層に、その作業に依存するコードはその上に配置します。レイヤーの選び方については、references/stack-design.md を参照してください。

セットアップ

gh extension install github/gh-stack
git config rerere.enabled true         # remember conflict resolutions
git config remote.pushDefault origin   # required if the repo has more than one remote

非対話的な使用

gh stack は、stdout が TTY かどうかに応じて動作を切り替えます。パイプ経由の場合、ほとんどのコマンドは適切にエラーを返すか静的テキストを出力しますが、PTY の場合、同じコマンドでもプロンプトまたは全画面 TUI が開き、処理が永久にブロックされます。エージェントのハーネスによって動作は異なるため、この判定に頼らず、必ず以下のフラグを渡してください。

複数のリモートがある場合： remote.pushDefault が設定されていない限り、--remote <name> なしで push、submit、sync、rebase、link を実行しないでください。checkout と trunk には --remote フラグがなく、設定が必要です。

常に実行する	引数なしで実行しない	理由
gh stack view --json	gh stack view	PTY では TUI が開きます
gh stack submit --auto	gh stack submit	新しい PR ごとにタイトルの入力を求められます
gh stack merge <target> --yes	gh stack merge	明示的に要求されたスタック全体のマージに範囲を限定します
gh stack init <branch>...	gh stack init	ブランチ名の入力を求められます
gh stack add <branch>	gh stack add	名前の入力を求められ、パイプ経由でも失敗します
gh stack checkout <target>	gh stack checkout	選択メニューが開きます
gh stack up / down / top / bottom	gh stack switch	switch はメニュー専用です
（なし）	gh stack modify	TUI 専用で、非対話的な方法はありません

• view --short はどちらのモードでも安全ですが、人間向けの形式で出力されます。解析には --json を使ってください。
• 別のローカルスタックが対象ブランチをすでに含んでいる場合、checkout <pr> を強制することはできません。 先に gh stack unstack --local を実行してください（GitHub 上のスタックはそのまま維持されます）。その後、再試行してください。

ブランチの配置

• 複数の部分からなる作業を始める場合： ファイルを作成する前にスタックを作成してください。すべての懸念事項をトランク上に実装してから、後で分割しないでください。依存する懸念事項をそれぞれ 1 つずつ、最下層から上に向かって配置します。
• 既存のスタックを編集する場合： 編集前に、変更を担当するレイヤーをチェックアウトしてください。現在の最上層ブランチに、下位レイヤーが担当する変更をコミットしないでください。gh stack view --json を実行してください。担当レイヤーが不明な場合は、git log --all -- <path> を確認します。その後、担当レイヤーをチェックアウトして編集、コミットし、上位のスタックをリベースしてから、最上層に戻ります。

gh stack down                   # or: gh stack checkout api
git add ... && git commit -m "Add get-user endpoint"
gh stack rebase --upstack       # replay every branch above onto the change
gh stack top                    # return to where you were
gh stack push

基本的な流れ

gh stack init auth              # create the stack and check out its branch
git add ... && git commit -m "Add auth middleware"
gh stack add api                # next layer, branched from the current one
git add ... && git commit -m "Add API routes"
gh stack submit --auto          # push every branch and open draft PRs
gh stack view --json            # confirm

submit に --open を追加すると、下書きではなくレビュー可能な状態で PR を作成できます。ブランチ名はそのまま使用されます。gh stack add refactor/foo は refactor/foo を作成します。

同期を維持する

gh stack sync                   # fetch, reconcile with GitHub, rebase, push, refresh PR state
gh stack sync --prune           # also delete local branches for merged PRs

非対話的な場合、--prune を指定しない限りプルーニングは行われません。ローカルとリモートのスタックが分岐している場合、sync は両方の連鎖を表示し、変更を加えず、Sync aborted として終了コード 0 で終了します。詳細は references/troubleshooting.md を参照してください。

マージ

複数の PR を取り込むとき、Jess はデフォルトでフォージを通じて順番にマージします。 merge-open-prs を使用します。まず親をマージし、次の PR にリポジトリのベース更新と検証の要件を適用します。 未マージの PR をマージする依頼を、1 つにまとめたスタック操作に変えてはいけません。

ユーザーがスタック全体のマージを依頼した場合に限り、以下のコマンドを使用します。 引数を指定してマージ対象を定めます。

gh stack merge 42 --yes          # PR #42 plus every unmerged PR below it
gh stack merge 7 --yes           # every unmerged PR in stack #7
gh stack merge 42 --yes --squash # or --merge, --rebase, --merge-method <method>

PR 番号を指定すると、その PR と、その下にある未マージの PR がすべてマージされます。スタック番号を指定すると、そのスタック内の未マージの PR がすべてマージされます。この操作は全件成功か全件失敗のいずれかです。対象の PR のいずれかをマージできない場合、どの PR もマージされません。

メソッドフラグを指定しない場合は、最後に使用したメソッドが再利用されます。ベースブランチでマージキューが使われている場合は、スタックがキューに登録され、キューがメソッドを選択します。フラグは無視され、その旨の警告が表示されます。キューに登録された PR は、別々のグループで取り込まれる場合があります。

状態の確認

gh stack view --json は JSON を stdout に出力します。ステータスメッセージは stderr に出力されます。ステータスメッセージを解析してはいけません。代わりに終了コードに応じて処理します。

trunk           string
currentBranch   string
branches[]      name, head, base, isCurrent, isMerged, isQueued, needsRebase
branches[].pr   number, url, state ("OPEN" | "MERGED" | "QUEUED"); absent when no PR exists

base は、このブランチが最後に含んでいることが確認された親ブランチの保存済み SHA です。親ブランチの現在の先端より古い場合があります。現在の親ブランチの先端がブランチの祖先ではなくなった場合、needsRebase は true になります。

終了コード

コード	意味	復旧方法
0	成功	（なし）
1	一般的なエラー	stderr を確認します
2	スタックに含まれていない	gh stack init または gh stack checkout <target>
3	リベースの競合	以下の終了コード 3 の復旧手順に従います
4	GitHub API の失敗	gh auth status を確認して再試行します
5	引数が無効	呼び出しを修正します。<command> --help を参照してください
6	対象の特定が必要	ブランチが複数のスタックに含まれています。共有されていないブランチをチェックアウトします
7	リベースがすでに進行中	gh stack rebase --continue または --abort
8	スタックファイルがロックされている	別の gh stack プロセスが書き込み中です。約 5 秒後に再試行します
9	スタックされた PR を利用できない	リポジトリで有効になっていません。ユーザーに伝えてください
10	変更の復旧が必要	gh stack modify --abort

終了コード 3 の復旧手順：

• gh stack rebase の後：ファイルの競合を解決し、git add を実行してから、 gh stack rebase --continue を実行します。スタックを元に戻すには gh stack rebase --abort を使用します。
• gh stack sync の後：スタックはすでに復元されています。gh stack rebase を実行して競合を再発生させ、その後、上記の手順に従って競合を解決し、続行します。

制約

• スタックは厳密な直線構造です。親は 1 つ、子は最大 1 つです。並行作業には別々のスタックを使用します。
• 非対話型の並べ替えや削除はできません。エラーに gh stack modify の使用が提案される場合がありますが、これは TUI 専用です。代わりに unstack を実行してから init で再構成してください。
• PR のタイトルと本文は自動生成されます。変更するには、その後 gh pr edit を使用してください。
• checkout <branch-name> はローカルのスタックのみを対象に解決します。GitHub からスタックを取得するには、スタック番号または PR 番号を使用します。

詳細

フラグと引数については gh stack <command> --help が正式な情報源です（gh stack help <command> は代わりにトップレベルのヘルプを表示します）。作業に応じたリファレンスを参照してください。

• references/stack-design.md：スタックを作成する前、およびレイヤー数や各レイヤーに含める内容を決める際に参照します。
• references/commands.md：コマンドが予期せず失敗した場合、またはその前提条件、副作用、原子性、順序の保証を確認する必要がある場合に参照します。
• references/troubleshooting.md：リベースの競合、スカッシュマージ後、ローカルとリモートの乖離、またはスタックの再構成時に参照します。