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 は、標準出力が 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 --squash	gh pr merge	gh pr 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 をご覧ください。

マージ

ユーザーが明示的にマージを依頼した場合に限り、スタックのマージを実行してください。まず gh stack view --json を確認し、スタック全体をマージするのか、特定の PR までをマージするのかを判断してから、引数と明示的な方法を指定してマージの対象範囲を設定してください。

gh stack merge 42 --yes --squash # PR #42 plus every unmerged PR below it
gh stack merge 7 --yes --squash  # every unmerged PR in stack #7

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

方法を省略すると最後に使用した方法が再利用されますが、エージェントは --squash、--merge、--rebase、または --merge-method <method> を明示的に指定する必要があります。ベースブランチでマージキューが使用されている場合、スタックはキューに追加され、キューがマージ方法を選択します。その場合、警告とともにフラグは無視されます。キューに追加された 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> は機能しない点に注意してください。トップレベルのヘルプが表示されます。

タスクに該当するトリガーのリファレンスを開いてください。3つすべてを事前に読み込む必要はありません。

• スタックを作成するとき、レイヤーの数や各レイヤーに含める内容を決めるとき、または作業を新しいスタックに含めるべきか判断するときは、references/stack-design.md を読んでください。
• コマンドが予期せず失敗したとき、またはその事前条件、副作用、アトミック性、順序の保証を確認する必要があるときは、references/commands.md を読んでください。
• リベースの競合が発生したとき、スカッシュマージ後、ローカルとリモートが乖離したとき、スタックを再構成するとき、または別のツールからスタックを操作するときは、references/troubleshooting.md を読んでください。