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 をお読みください。

セットアップ

Git 2.36 以降と、認証済みの GitHub CLI が必要です。

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 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 上のスタックは維持されます）。その後、再試行してください。
• ワークツリー： ローカルスタックは共通ディレクトリのカタログを共有します。別のブランチのチェックアウトを奪わずに、別の場所が所有するブランチを見つけるには、ナビゲーションまたは対象を明示した checkout で --print-path を使用してください。占有されていない対象は、まずここでチェックアウトされます。ディレクトリを変更する前に終了ステータスを確認してください。パスモードの stdout は、成功した場合のみ解析し、ステータスメッセージは解析しないでください。

ブランチの配置

• 複数のパートからなる作業を始める場合： ファイルを作成する前にスタックを作成してください。トランクですべての作業を実装してから、後で分割しないでください。依存する内容を 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 は両方のチェーンを表示して変更を加えず、終了コード 0 で Sync aborted を出力します。詳しくは references/troubleshooting.md を参照してください。

マージ

引数を指定して、マージの対象範囲を定めます。

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	modify の復旧が必要	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 つです。並行作業には別々のスタックを使用してください。
• rebase と sync は、影響を受けるクリーンなワークツリーを自動的に更新します。自動で stash したり、ワークツリーを作成・削除したりすることはありません。変更操作はクローン全体で直列化され、中断された操作は記録された所有者の環境で復旧する必要があります。
• modify は分散したスタックブランチに対応していますが、エディターは TUI 専用です。操作は、影響を受けるクリーンな所有者の環境で実行されます。占有されていないブランチでは origin が使われます。drop/fold の対象となったソースブランチとワークツリーは保持されます。復旧フラグはどのワークツリーからでも実行でき、記録されたネイティブ操作の所有者が使われます。診断で呼び出し元のツリーが指定されていない限り、呼び出し元のツリーで競合の解決やステージングをしないでください。
• 非対話型の並べ替えや削除には対応していません。エラーで gh stack modify が提案される場合がありますが、これは TUI 専用です。その代わり、unstack の後に init を実行して構成を変更してください。
• PR のタイトルと本文は自動生成されます。変更する場合は、その後 gh pr edit を使用してください。

詳細情報

gh stack <command> --help のフラグと引数の説明が正式な情報です。gh stack help <command> は機能しない点に注意してください。トップレベルのヘルプが表示されます。

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

• references/stack-design.md — スタックの作成時、使用するレイヤーの数や各レイヤーに含める内容を決めるとき、または作業を新しいスタックに含めるべきか判断するときに読みます。
• references/commands.md — コマンドが予期せず失敗したとき、またはコマンドの前提条件、副作用、アトミック性、順序保証を確認するときに読みます。
• references/troubleshooting.md — リベースの競合、squash merge の後、ローカルとリモートの不整合、スタックの再構成時、または別のツールからスタックを操作するときに読みます。