gh-stack

gh stack は スタックされたブランチとプルリクエストを管理する GitHub CLI 拡張機能です。スタックは、順序付きのブランチリストで、各ブランチがその下のブランチの上に構築され、トランクブランチ（通常はリポジトリのデフォルトブランチ）をベースとしています。各ブランチは1つのPRにマップされ、そのベースはその下のブランチとなります。レビュアーはそのレイヤーの差分のみを見ます。

main (trunk)
 └── feat/auth-layer     → PR #1 (base: main)               - bottom (closest to trunk)
  └── feat/api-endpoints → PR #2 (base: feat/auth-layer)
   └── feat/frontend     → PR #3 (base: feat/api-endpoints) - top (furthest from trunk)

スタックの bottom はトランクに最も近いブランチで、top はトランクから最も遠いブランチです。各ブランチはその下のブランチから継承されます。ナビゲーションコマンド (up, down, top, bottom) はこのモデルに従います: up はトランクから離れる方向に移動し、down はトランクに向かう方向に移動します。

このスキルを使用する場合

ユーザーが以下の操作を希望する場合にこのスキルを使用してください:

• 大規模な変更を小さくレビュー可能なPRのチェーンに分割する
• 依存するブランチのスタックを作成、リベース、プッシュ、または同期する
• ブランチスタックのレイヤー間を移動する
• スタックされたPRのステータスを表示する
• ブランチを削除、並べ替え、または名前変更するためにスタックを削除して再構築する

前提条件

GitHub CLI (gh) v2.0以上がインストールされており、認証されている必要があります。拡張機能は以下でインストールしてください:

gh extension install github/gh-stack

gh stack を使用する前に、git を設定してインタラクティブなプロンプトを防ぎます:

git config rerere.enabled true           # remember conflict resolutions (skips prompt on init)
git config remote.pushDefault origin     # if multiple remotes exist (skips remote picker)

エージェントルール

すべての gh stack コマンドはノンインタラクティブモードで実行する必要があります。 すべてのコマンド呼び出しには、プロンプト、TUI、およびインタラクティブメニューを避けるために必要なフラグと位置指定引数を含める必要があります。コマンドがプロンプトを出す場合、無限にハングします。

1. 常にブランチ名を位置指定引数として init, add, checkout に供給してください。 これらのコマンドを引数なしで実行するとインタラクティブなプロンプトが起動されます。
2. プレフィックスが設定されている場合は、サフィックスのみを add に渡してください。 gh stack add auth (プレフィックス feat) → feat/auth。feat/auth を渡すと feat/feat/auth が作成されます。
3. 常に --auto を gh stack submit で使用してください PR タイトルを自動生成するため。--auto なしでは、submit は新しい PR ごとにタイトルのプロンプトを出します。
4. 常に --json を gh stack view で使用してください。 --json なしでは、コマンドはエージェントが操作できないインタラクティブな TUI を起動します。他に適切なフラグはありません — 常に --json を渡してください。
5. 複数のリモートが構成されている場合は --remote <name> を使用してください。または git config remote.pushDefault origin で事前構成します。これなしでは、push, submit, sync, link, checkout がインタラクティブなリモートピッカーを起動します。
6. 複数のスタック間で共有されるブランチを避けてください。 ブランチが複数のスタックに属している場合、コマンドはコード 6 で終了します。最初に共有されていないブランチをチェックアウトしてください。
7. コードを書く前に、スタックレイヤーを依存関係の順序で計画してください。 基盤となる変更（モデル、API、共有ユーティリティ）は下位のブランチに入り、依存する変更（UI、コンシューマー）は上位のブランチに入ります。gh stack init を実行する前に依存関係チェーンをよく考えてください。
8. ステージングとコミットのために標準の git add と git commit を使用してください。 これにより、どの変更を各ブランチに入れるかを完全に制御できます。-Am ショートカットは利用可能ですが、デフォルトのアプローチではなくてはいけません — スタックされた PR は各ブランチが意図的で論理的な変更セットを含む場合に最も効果的です。
9. 下位レイヤーを変更する必要がある場合はスタックを下に移動してください。 フロントエンドブランチで作業していて API 変更が必要だと気づいた場合、現在のレイヤーで回避策を使わないでください。適切なブランチ (gh stack down, gh stack checkout, または gh stack bottom) に移動し、そこで変更を加えてコミットし、gh stack rebase --upstack を実行して、上に戻って続行してください。
10. 外部ツールワークフローに gh stack link を使用してください。 ブランチが外部ツール（jj、Sapling など）によって管理されている場合は、gh stack link branch-a branch-b を使用してください。link はローカルのトラッキング状態に依存せず、API駆動型の PR およびスタック管理を目的としています。常に最低 2 つのブランチ名または PR 番号を提供してください。

以下のいずれも行わないでください — それぞれがハングするインタラクティブなプロンプトまたは TUI をトリガーします:

• ❌ gh stack view または gh stack view --short — 常に gh stack view --json を使用してください
• ❌ gh stack submit (without --auto) — 常に gh stack submit --auto を使用してください
• ❌ gh stack init (without branch arguments) — 常にブランチ名を指定してください
• ❌ gh stack add (without a branch name) — 常にブランチ名を指定してください
• ❌ gh stack checkout (without an argument) — 常に PR 番号またはブランチ名を指定してください
• ❌ gh stack checkout <pr-number> (when a different local stack already exists on those branches) — これはバイパスできない競合解決プロンプトをトリガーします。最初に gh stack unstack を使用してローカルスタックを削除してから、チェックアウトを再試行してください

スタック構造についての考察

スタック内の各ブランチは、独立してレビューできる 離散的で論理的な作業単位 を表すべきです。ブランチ内の変更は首尾一貫しており、一緒に属しており、単一の PR として意味があります。

依存関係チェーン

スタックされたブランチは依存関係チェーンを形成します: 各ブランチはその下のブランチの上に構築されます。これは 基盤となる変更は下位（前に）のブランチに入り、それらに依存するコードは上位（後に）のブランチに入る ことを意味します。

コードを書く前にレイヤーを計画してください。 例えば、フルスタック機能は次のように構成されるかもしれません（これらのジェネリック名ではなく、実際のタスクに関連するブランチ名を使用してください）:

main (trunk)
 └── feat/data-models    ← shared types, database schema
  └── feat/api-endpoints ← API routes that use the models
   └── feat/frontend-ui  ← UI components that call the APIs
    └── feat/integration ← tests that exercise the full stack

これは説明的です — あなたが実際に行っている作業を反映するブランチ名とレイヤー境界を選択してください。重要な原則は: あるレイヤーのコードが別のレイヤーのコードに依存している場合、依存関係は同じブランチまたは下位のブランチに存在する必要があります。

ブランチ命名

プレフィックス (-p) を使ってスタックを初期化することを推奨します。プレフィックスはブランチを名前空間の下にグループ化し（例: feat/auth, feat/api）、ブランチ名を清潔で一貫性のあるものにします。プレフィックスが設定されている場合、後続の add 呼び出しにはサフィックスのみを渡します — プレフィックスは自動的に適用されます。プレフィックスなしでは、毎回フルブランチ名を渡す必要があります。

意図的に変更をステージングする

git add と git commit を直接使用する主な理由は、どの変更を各ブランチに入れるかを制御する ことです。ワーキングツリーに複数のファイルがある場合、現在のブランチのサブセットをステージングし、それらをコミットしてから、新しいブランチを作成して残りをそこにステージングできます:

# You're on feat/data-models with several new files in your working tree.
# Stage only the model files for this branch:
git add internal/models/user.go internal/models/session.go
git commit -m "Add user and session models"

git add db/migrations/001_create_users.sql
git commit -m "Add user table migration"

# Now create a new branch for the API layer and stage the API files there:
gh stack add api-routes # created & switched to feat/api-routes branch
git add internal/api/routes.go internal/api/handlers.go
git commit -m "Add user API routes"

これにより各ブランチが 1 つの関心事に焦点を当てます。ブランチあたり複数のコミットは問題ありません — 重要なのは、ブランチ内のすべてのコミットが同じ論理的関心事に関連していること、および異なる関心事に属する変更が異なるブランチに入ることです。

新しいブランチを作成するタイミング

これまで構築したものに依存する 異なる関心事 を開始するときに新しいブランチを作成してください (gh stack add)。新しいブランチの時期を示すサイン:

• バックエンドからフロントエンド作業に切り替えている
• コアロジックからテストまたはドキュメントに移動している
• 次の変更セットは異なるレビュアー対象を持っている
• 現在のブランチの PR はすでにレビューするのに十分な大きさである

1 つのスタック、1 つのストーリー

レビュアーの視点からスタックを考えてください: PR のスタックは、機能またはプロジェクトについての 首尾一貫したストーリー を語るべきです。レビュアーは順番に PR を読むことができ、変更の進行を理解し、各 PR が全体の小さく論理的な部分であるべきです。

単一のスタックを使用する場合: すべてのブランチが同じ機能、プロジェクト、または密接に関連する努力の一部です。作業が複数の関心事（モデル、API、フロントエンド）にまたがっていても、それらはすべて同じ目標に向かって構築しています。

別のスタックを作成する場合: 作業は現在のスタックと無関係です — 異なる機能、無関係な領域のバグ修正、または独立したリファクタリング。両方に取り組んでいるからといって、無関係な作業を単一のスタックに混ぜないでください。各明確な努力に対して gh stack init で新しいスタックを開始するか、gh stack checkout で既存のスタックに切り替えてください。

小さな付随的な修正（例: 気付いた タイプミスの修正）は些細であれば現在のスタックに入ることができます。しかし変更が自身のプロジェクトに成長した場合、独自のスタックに値します。

クイックリファレンス

タスク	コマンド
スタックを作成（推奨）	gh stack init -p feat auth
プレフィックスなしでスタックを作成	gh stack init auth
複数のブランチのスタックを作成	gh stack init auth api frontend
既存のブランチを採用	gh stack init existing-branch-a existing-branch-b
カスタムトランクを設定	gh stack init --base develop branch-a
スタックにブランチを追加（プレフィックス設定時はサフィックスのみ）	gh stack add api-routes
ブランチを追加 + すべてをステージング + コミット	gh stack add -Am "message" api-routes
ブランチをリモートにプッシュ	gh stack push
特定のリモートにプッシュ	gh stack push --remote origin
ブランチをプッシュ + ドラフト PR を作成	gh stack submit --auto
PR をレビュー準備完了として作成	gh stack submit --auto --open
同期（フェッチ、リベース、プッシュ）	gh stack sync
特定のリモートと同期	gh stack sync --remote origin
同期とマージ済みブランチをプルーン	gh stack sync --prune
スタック全体をリベース	gh stack rebase
アップスタックのみをリベース	gh stack rebase --upstack
競合後に続行	gh stack rebase --continue
リベースを中止	gh stack rebase --abort
スタック詳細を表示（JSON）	gh stack view --json
スタック内をアップ/ダウンに切り替え	gh stack up [n] / gh stack down [n]
トップ/ボトムブランチに切り替え	gh stack top / gh stack bottom
PR でチェックアウト	gh stack checkout 42
ブランチでチェックアウト（ローカルのみ）	gh stack checkout feature-auth
スタックを削除して再構築	gh stack unstack

---

ワークフロー

エンドツーエンド: ゼロからスタックを作成

# 1. Initialize a stack with the first branch
gh stack init -p feat auth
# → creates feat/auth and checks it out

# 2. Write code for the first layer (auth)
cat > auth.go << 'EOF'
package auth

func Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // verify token
        next.ServeHTTP(w, r)
    })
}
EOF

# 3. Stage and commit using standard git commands
git add auth.go
git commit -m "Add auth middleware"

# You can make multiple commits on the same branch
cat > auth_test.go << 'EOF'
package auth

func TestMiddleware(t *testing.T) {
    // test auth middleware
}
EOF
git add auth_test.go
git commit -m "Add auth middleware tests"

# 4. When you're ready for a new concern, add the next branch
gh stack add api-routes
# → creates feat/api-routes (prefix applied automatically — just pass the suffix)

# 5. Write code for the API layer
cat > api.go << 'EOF'
package api

func RegisterRoutes(mux *http.ServeMux) {
    mux.HandleFunc("/users", handleUsers)
}
EOF
git add api.go
git commit -m "Add API routes"

# 6. Add a third layer for frontend
gh stack add frontend
# → creates feat/frontend (just the suffix — prefix is automatic)

cat > frontend.go << 'EOF'
package frontend

func RenderDashboard(w http.ResponseWriter) {
    // calls the API endpoints from the layer below
}
EOF
git add frontend.go
git commit -m "Add frontend dashboard"

# ── Stack complete: feat/auth → feat/api-routes → feat/frontend ──

# 7. Push everything and create PRs (drafts by default)
gh stack submit --auto

# 8. Verify the stack
gh stack view --json

ショートカット: より高速なフローを希望する場合、gh stack add -Am "message" branch-name はステージング、コミット、ブランチ作成を 1 つのコマンドに組み合わせます。これはシングルコミットレイヤーに便利ですが、意図的なステージングをバイパスします。

中位置のスタック変更

これはエージェントの重要なワークフローです。高いレイヤーで作業していて、下位レイヤーで何かを変更する必要があることに気づいた場合（例: フロントエンドコンポーネントを構築していますが API エンドポイントを追加する必要がある場合）、正しいブランチに移動し、そこで変更を加えてリベースしてください。

# You're on feat/frontend but need to add an API endpoint

# 1. Navigate to the API branch
gh stack down
# or: gh stack checkout feat/api-routes

# 2. Make the change where it belongs
cat > users_api.go << 'EOF'
package api

func handleGetUser(w http.ResponseWriter, r *http.Request) {
    // new endpoint the frontend needs
}
EOF
git add users_api.go
git commit -m "Add get-user endpoint"

# 3. Rebase everything above to pick up the change
gh stack rebase --upstack

# 4. Navigate back to where you were working
gh stack top
# or: gh stack checkout feat/frontend

# 5. Continue working — the API changes are now available

これが重要な理由: フロントエンドブランチで API 変更を加えると、それらの変更は間違った PR に入ります。API PR にそれらが含まれず、フロントエンド PR に無関係な API diff が混在します。常に論理的に属する場所のブランチに変更を入れてください。

中位置のブランチを変更して同期

初期作成後にブランチを再び訪問する必要がある場合（例: レビューフィードバックに対応する場合）:

# 1. Navigate to the branch that needs changes
gh stack bottom
# or: gh stack checkout feat/auth
# or: gh stack checkout 42  (by PR number)

# 2. Make changes and commit
cat > auth.go << 'EOF'
package auth
// updated implementation
EOF
git add auth.go
git commit -m "Fix auth token validation"

# 3. Rebase everything above this branch
gh stack rebase --upstack

# 4. Push the updated stack
gh stack push

マージ後の定期的な同期

# Single command: fetch, rebase, push, sync PR state
gh stack sync

# Sync and automatically clean up local branches for merged PRs
gh stack sync --prune

エージェント向けの注記: ノンインタラクティブな環境では、プルーンプロンプトは表示されません。マージされた PR のローカルブランチを削除するには、明示的に --prune を使用してください。

スカッシュマージ復旧

PR が GitHub でスカッシュマージされると、元のブランチのコミットはトランク履歴に存在しなくなります。gh stack はこれを自動的に検出し、git rebase --onto を使用して残りのコミットを正しく再生します。

# After PR #1 (feat/auth) is squash-merged on GitHub:
gh stack sync
# → fetches latest, detects the merge, fast-forwards trunk
# → rebases feat/api-routes onto updated trunk (skips merged branch)
# → rebases feat/frontend onto feat/api-routes
# → pushes updated branches
# → reports: "Merged: #1"

# Verify the result
gh stack view --json
# → feat/auth shows "isMerged": true, "state": "MERGED"
# → feat/api-routes and feat/frontend show updated heads

sync がこのプロセス中に競合にぶつかった場合、すべてのブランチをリベース前の状態に復元し、コード 3 で終了します。解決ワークフローについては リベース競合の処理 を参照してください。

リベース競合の処理（エージェントワークフロー）

# 1. Start the rebase
gh stack rebase

# 2. If exit code 3 (conflict):
#    - Parse stderr for conflicted file paths
#    - Read those files to find <<<<<<< / ======= / >>>>>>> markers
#    - Edit files to resolve conflicts
#    - Stage resolved files:
git add path/to/resolved-file.go

# 3. Continue the rebase
gh stack rebase --continue

# 4. If another conflict occurs, repeat steps 2-3

# 5. If unable to resolve, abort to restore everything
gh stack rebase --abort

--json 出力をパースする

# Get stack state as JSON
output=$(gh stack view --json)

# Check if any branch needs a rebase, and rebase if so
needs_rebase=$(echo "$output" | jq '[.branches[] | select(.needsRebase == true)] | length')
if [ "$needs_rebase" -gt 0 ]; then
  echo "Branches need rebase, rebasing stack..."
  gh stack rebase
fi

# Get all open PR URLs
echo "$output" | jq -r '.branches[] | select(.pr.state == "OPEN") | .pr.url'

# Find merged branches
echo "$output" | jq -r '.branches[] | select(.isMerged == true) | .name'

# Get the current branch
echo "$output" | jq -r '.currentBranch'

# Check if the stack is fully merged (all branches merged)
echo "$output" | jq '[.branches[] | .isMerged] | all'

スタックを再構築（ブランチを削除、並べ替え、または名前変更）

unstack を使用してスタックを削除し、構造的な変更を加えてから再初期化します:

# 1. Remove the stack (locally and on GitHub)
gh stack unstack

# 2. Make structural changes — e.g. delete a branch, reorder, rename
git branch -m old-branch-1 new-branch-1

# 3. Re-create the stack with the new structure
gh stack init --base main new-branch-1 new-branch-2 new-branch-3

---

コマンド

スタックを初期化 — gh stack init

新しいスタックを作成します。常に位置指定引数として少なくとも 1 つのブランチ名を指定してください — ブランチ引数なしで実行すると、エージェントが使用できないインタラクティブなプロンプトが起動されます。

gh stack init [flags] <branches...>

# Set a branch prefix (recommended — subsequent `add` calls only need the suffix)
gh stack init -p feat auth
# → creates feat/auth

# Multi-part prefix (slashes are fine — suffix-only rule still applies)
gh stack init -p monalisa/billing auth
# → creates monalisa/billing/auth

# Create a stack with new branches (no prefix — use full branch names)
gh stack init branch-a branch-b branch-c

# Use a different trunk branch
gh stack init --base develop branch-a branch-b

# Adopt existing branches into a stack (handled automatically if the branches exist)
gh stack init branch-a branch-b branch-c

フラグ	説明
-b, --base <branch>	トランクブランチ（デフォルト: リポジトリのデフォルトブランチ）
-p, --prefix <string>	ブランチ名プレフィックス。後続の add 呼び出しはサフィックスのみが必要です（例: -p feat の場合、gh stack add auth は feat/auth を作成します）

動作:

• -p を使用することを推奨します — 後続の add 呼び出しのためのブランチ命名を簡素化します
• 存在しないブランチを作成します（トランクブランチからブランチ化）
• 既存のブランチは自動的に採用されます；欠落しているブランチはトランクから作成されます
• リスト内の最後のブランチをチェックアウトします
• git rerere を有効化します。リポジトリでの最初の実行時に確認プロンプトがトリガーされる場合があります — git config rerere.enabled true で事前構成してそれを避けます

---

ブランチを追加 — gh stack add

スタックの現在のトップに新しいブランチを追加します。トップのブランチ（またはスタックにブランチがない場合はトランク）で実行する必要があります。常にブランチ名を指定してください — ブランチ名なしで実行するとインタラクティブなプロンプトが起動されます。

gh stack add [flags] <branch>

推奨ワークフロー — ブランチを作成し、その後標準の git を使用:

# Create a new branch and switch to it (just the suffix — prefix is applied automatically)
gh stack add api-routes

# Write code, stage deliberately, and commit
git add internal/api/routes.go internal/api/handlers.go
git commit -m "Add user API routes"

# Make more commits on the same branch as needed
git add internal/api/middleware.go
git commit -m "Add rate limiting middleware"

ショートカット — ステージング、コミット、ブランチを 1 つのコマンドで:

# Create a new branch, stage all changes, and commit
gh stack add -Am "Add API routes" api-routes

# Create a new branch, stage tracked files only, and commit
gh stack add -um "Fix auth bug" auth-fix

フラグ	説明
-m, --message <string>	このメッセージでコミットを作成する
-A, --all	未追跡ファイルを含むすべての変更をステージング（-m が必須）
-u, --update	追跡されたファイルのみをステージング（-m が必須）

動作に関するメモ:

• -A と -u は相互に排他的です。
• 現在のブランチにコミットがない場合（例: init の直後）、add -Am は新しいブランチを作成する代わりに現在のブランチに直接コミットします。
• プレフィックス処理: プレフィックスが設定されている場合、サフィックスのみを渡します。プレフィックス todo で gh stack add api → todo/api。todo/api を渡すと todo/todo/api が作成されます。プレフィックスなしで、フルブランチ名を渡します。
• スタックのトップのブランチではないブランチから呼び出された場合、コード 5 で終了します: "can only add branches on top of the stack"。最初に gh stack top で切り替えてください。
• コミットされていない変更: -Am なしで gh stack add branch-name を使用すると、ワーキングツリー内のコミットされていない変更（ステージングまたはステージングされていない）は新しいブランチに引き継がれます。これは標準の git 動作です — ワーキングツリーは変更されません。変更をコミットするか、新しいブランチでクリーンな開始ポイントが必要な場合は、add を実行する前に現在のブランチに変更をスタッシュしてください。

---

ブランチをリモートにプッシュ — gh stack push

すべてのスタックブランチをリモートにプッシュします。

gh stack push [flags]

# Push all branches
gh stack push

# Push to specific remote
gh stack push --remote upstream

フラグ	説明
--remote <name>	プッシュ先のリモート（複数のリモートが存在する場合に使用）

動作:

• すべてのアクティブ（マージされていない）なブランチをアトミックにプッシュします（--force-with-lease --atomic）
• プルリクエストを作成または更新しません — PR については gh stack submit を使用してください

出力（stderr）:

• Pushed N branches サマリー

---

ブランチを提出して PR を作成 — gh stack submit

すべてのスタックブランチをプッシュして GitHub で PR を作成します。常に --auto を渡してください — なしでは、submit は新しい PR ごとに PR タイトルのプロンプトを出します。

# Submit and auto-title new PRs (required for non-interactive use)
gh stack submit --auto

# Submit and create PRs as ready for review (not drafts)
gh stack submit --auto --open

フラグ	説明
--auto	プロンプトなしで PR タイトルを自動生成（ノンインタラクティブ使用に必須）
--open	新しいおよび既存の PR をレビュー準備完了としてマーク
--remote <name>	プッシュ先のリモート（複数のリモートが存在する場合に使用）

動作:

• すべてのアクティブ（マージされていない）なブランチをアトミックにプッシュします（--force-with-lease --atomic）
• PR を持たない各ブランチに新しい PR を作成します（ベースは最初のマージされていない前向きブランチに設定）
• PR を作成した後、GitHub で Stack として一緒にリンクします（リポジトリにスタックが有効になっている必要があります）
• スタックが利用できない場合（コード 9）、リポジトリにスタックされた PR が有効になっていません。インタラクティブモードでは、submit は通常の（スタックされていない）PR を作成することを提供します。ノンインタラクティブモードでは、コード 9 で終了します。
• すでに PR を持つブランチの PR メタデータを同期します

PR タイトル自動生成（--auto）:

• ブランチ上の単一コミット → コミット件名を PR タイトルとして使用、コミット本体を PR 本体として使用
• ブランチ上の複数コミット → ブランチ名を人間化（ハイフン/アンダースコア → スペース）してタイトルとして使用

出力（stderr）:

• 新しく作成された PR ごとに Created PR #N for <branch>
• 既存 PR ごとに PR #N for <branch> is up to date
• Pushed and synced N branches サマリー

---

ブランチをスタックとしてリンク（ローカルトラッキングなし） — gh stack link

ローカルトラッキング状態を作成することなく PR を GitHub のスタックにリンクしてください。他のツール（jj、Sapling、git-town）でスタックされたブランチを管理していて、API 経由で GitHub Stacked PR を作成したい場合、これは推奨されるアプローチです。

gh stack link [flags] <branch-or-pr> <branch-or-pr> [...]

# Link branches into a stack (pushes, creates PRs, creates stack)
gh stack link branch-a branch-b branch-c

# Use a different base branch and mark PRs as ready for review
gh stack link --base develop --open branch-a branch-b branch-c

# Link existing PRs by number
gh stack link 10 20 30

# Add branches to an existing stack of PRs
gh stack link 42 43 feature-auth feature-ui

フラグ	説明
--base <branch>	スタックのボトムのベースブランチ（デフォルト: main）
--open	新しいおよび既存の PR をレビュー準備完了としてマーク
--remote <name>	プッシュ先のリモート（複数のリモートが存在する場合に使用）

動作:

• 引数はスタック順（ボトムからトップ）で指定されます
• 各引数はブランチ名または PR 番号です。数値引数は最初に PR 番号として試行されます; そのような PR 番号が存在しない場合、引数はブランチ名として扱われます
• ブランチ引数は自動的にリモートにプッシュされます（非フォース、アトミック）
• オープン PR を持たないブランチについて、自動生成されたタイトルと正しいベースブランチチェーン（最初のブランチが --base を使用、後続ブランチが前のブランチを使用）で新しい PR が作成されます
• ベースブランチが期待されるチェーンと一致しない既存 PR は自動的に修正されます
• PR がまだスタック内にない場合、新しいスタックが作成されます。一部の PR が既にスタック内にある場合、スタックは更新されます（加算のみ — 既存 PR は削除されません）
• ローカル状態を作成または変更しません

出力（stderr）:

• Pushing N branches to <remote>...
• 既存 PR を持つブランチごとに Found PR #N for branch <name>
• 新しく作成された PR ごとに Created PR #N for <branch> (base: <base>)
• ベースブランチが修正されるとき Updated base branch for PR #N to <base>
• Created stack with N PRs または Updated stack to N PRs

---

スタックを同期 — gh stack sync

フェッチ、リベース、プッシュ、PR 状態の同期を 1 つのコマンドで行います。これはルーチン同期化に推奨されるコマンドです。

gh stack sync [flags]

フラグ	説明
--remote <name>	フェッチとプッシュ先のリモート（複数のリモートが存在する場合に使用）
--prune	マージされた PR のローカルブランチを削除

動作（順序）:

1. フェッチ リモートから最新の変更を取得
2. トランクをファストフォワード リモートと一致させます（既に最新の場合スキップ、分岐した場合警告）
3. カスケードリベース すべてのスタックブランチを更新された親の上にリベースします（トランクが移動した場合のみ）。マージされた PR を自動的に処理します。競合が検出された場合、すべてのブランチがリベース前の状態に復元され、コマンドはコード 3 で終了します — 解決ワークフローについては リベース競合の処理 を参照してください
4. プッシュ すべてのアクティブブランチをアトミックにプッシュ
5. PR 状態を同期 GitHub から PR 状態を同期し、各 PR のステータスを報告
6. プルーン — インタラクティブターミナルで、マージされた PR のローカルブランチを削除するようプロンプトします。--prune を使用してプロンプトをスキップします。ノンインタラクティブ環境では、--prune が明示的に渡されたときにのみプルーニングが発生します

出力（stderr）:

• ✓ Fetched latest changes from origin
• ✓ Trunk main fast-forwarded to <sha> または ✓ Trunk main is already up to date
• ✓ Rebased <branch> onto <base> ブランチごと（ベースが移動した場合）
• ✓ Pushed N branches
• ✓ PR #N (<branch>) — Open ブランチごと
• Merged: #N, #M マージされたブランチ用
• ✓ Pruned <branch> (merged) プルーンされたブランチごと（プルーニング時）
• ✓ Stack synced

---

スタックをリベース — gh stack rebase

リモートからプルし、スタックブランチをカスケードリベースします。sync が競合を報告する場合、または細かい制御が必要な場合（例: スタックの一部のみをリベース）に使用します。

gh stack rebase [flags] [branch]

# Rebase the entire stack
gh stack rebase

# Rebase only branches from trunk to current branch
gh stack rebase --downstack

# Rebase only branches from current branch to top
gh stack rebase --upstack

# After resolving a conflict: stage files with `git add`, then:
gh stack rebase --continue

# Abort and restore all branches to pre-rebase state
gh stack rebase --abort

フラグ	説明
--downstack	トランクから現在のブランチまでのブランチのみをリベース
--upstack	現在のブランチからトップまでのブランチのみをリベース
--continue	競合を解決した後に続行
--abort	中止してすべてのブランチを復元
--remote <name>	フェッチ先のリモート（複数のリモートが存在する場合に使用）

引数	説明
[branch]	ターゲットブランチ（デフォルト: 現在のブランチ）

競合処理: ワークフローセクションで リベース競合の処理 を参照して完全な解決ワークフローを確認してください。

マージされた PR 検出: ブランチの PR が GitHub にマージされた場合、リベースは --onto モードを使用してこれを自動的に処理し、マージターゲットの上にコミットを正しく再生します。

Rerere（競合メモリ）: git rerere は init によって有効化されるため、以前に解決された競合は将来のリベースで自動的に解決されます。

---

スタックを表示 — gh stack view

現在のスタックのブランチ、PR ステータス、最近のコミットを表示します。常に --json を渡してください — なしでは、このコマンドはエージェントが操作できないインタラクティブな TUI を起動します。

# Always use --json
gh stack view --json

フラグ	説明
--json	スタックデータを JSON として stdout に出力（ノンインタラクティブ使用に必須）

--json 出力形式:

{
  "trunk": "main",
  "prefix": "feat",
  "currentBranch": "feat/api-routes",
  "branches": [
    {
      "name": "feat/auth",
      "head": "abc1234...",
      "base": "def5678...",
      "isCurrent": false,
      "isMerged": true,
      "needsRebase": false,
      "pr": {
        "number": 42,
        "url": "https://github.com/owner/repo/pull/42",
        "state": "MERGED"
      }
    },
    {
      "name": "feat/api-routes",
      "head": "789abcd...",
      "base": "abc1234...",
      "isCurrent": true,
      "isMerged": false,
      "needsRebase": false,
      "pr": {
        "number": 43,
        "url": "https://github.com/owner/repo/pull/43",
        "state": "OPEN"
      }
    }
  ]
}

ブランチあたりのフィールド:

• name — ブランチ名
• head — 現在の HEAD SHA
• base — 最後の同期時の親ブランチの HEAD SHA
• isCurrent — これはチェックアウトされたブランチか
• isMerged — PR がマージされているか
• needsRebase — ベースブランチが祖先ではないか（非線形履歴）
• pr — PR メタデータ（PR が存在しない場合は省略）。state は "OPEN" または "MERGED" です。

---

スタックをナビゲート

ブランチ名を覚えることなくブランチ間を移動します。これらのコマンドは完全にノンインタラクティブです。

gh stack up          # Move up one branch (further from trunk)
gh stack up 3        # Move up three branches
gh stack down        # Move down one branch (closer to trunk)
gh stack down 2      # Move down two branches
gh stack top         # Jump to the top of the stack (furthest from trunk)
gh stack bottom      # Jump to the bottom (first non-merged branch above trunk)

ナビゲーションはスタック境界にクランプされます。マージされたブランチはアクティブブランチからナビゲートする場合スキップされます。

---

スタックをチェックアウト — gh stack checkout

プルリクエスト番号またはブランチ名からスタックをチェックアウトします。常に引数を指定してください — 引数なしで gh stack checkout を実行するとインタラクティブな選択メニューが起動されます。

gh stack checkout <pr-number | branch>

# By PR number (pulls from GitHub)
gh stack checkout 42

# By branch name (local only)
gh stack checkout feature-auth

PR 番号が指定されている場合（例: 123）、コマンドは GitHub のスタックをフェッチし、ブランチをプルして、スタックをローカルで設定します。スタックが既にローカルに存在し、一致する場合、ブランチに切り替わります。

⚠️ エージェント警告: ローカルとリモートのスタックが異なるブランチ構成を持っている場合、このコマンドはフラグでバイパスできないインタラクティブな競合解決プロンプトをトリガーします。これを避けるため: 最初に gh stack unstack を実行して競合するローカルスタックを削除してから、gh stack checkout <pr-number> を再試行してください。

ブランチ名が指定されている場合、コマンドはローカルでトラッキングされたスタックに対してそれを解決します。これはノンインタラクティブ使用に対して常に安全です。

---

スタックを削除 — gh stack unstack

スタックを削除して再構築できるようにします — ブランチを削除、ブランチを並べ替え、ブランチを名前変更、または他の大規模な変更を加えます。アンスタック後、gh stack init を使用してスタックを目的の構造で再作成します。

スタックのブランチをローカルでチェックアウトしておく必要があります。コマンドはアクティブなスタック — チェックアウトされたブランチを含むスタック — を対象とします。

gh stack unstack [flags]

# Tear down the stack (locally and on GitHub), then rebuild
gh stack unstack
gh stack init --base main branch-2 branch-1 branch-3 # reordered

# Only remove local tracking (keep the stack on GitHub)
gh stack unstack --local

フラグ	説明
--local	ローカルでのみスタックを削除（GitHub 上は保持）

---

出力規約

• ステータスメッセージ は stderr に emoji プレフィックス付きで出力されます: ✓（成功）、✗（エラー）、⚠（警告）、ℹ（情報）。
• データ出力（例: view --json）は stdout に出力されます。
• 出力をパイプする場合、データ出力のみが必要な場合は 2>/dev/null を使用してステータスメッセージを抑制します。

終了コードとエラー復旧

コード	意味	エージェントのアクション
0	成功	通常どおり進行
1	ジェネリックエラー	stderr の詳細を読む；コミット/プッシュ失敗を示す場合があります
2	スタック内ではない	gh stack init を実行してスタックを最初に作成します
3	リベース競合	stderr から競合ファイルパスをパース、競合を解決、gh stack rebase --continue を実行
4	GitHub API 失敗	gh auth status をチェック、コマンドを再試行
5	無効な引数	コマンド呼び出しを修正（フラグと引数をチェック）
6	曖昧性解決が必要	ブランチが複数のスタックに属しています。gh stack checkout <specific-branch> を実行して共有されていないブランチに切り替えてください
7	リベースが進行中	gh stack rebase --continue を実行（競合を解決した後）または gh stack rebase --abort を実行して最初からやり直す
8	スタックがロックされている	別の gh stack プロセスがスタックファイルに書き込み中。ロックは 5 秒後にタイムアウトするため、待機して再試行してください
9	スタックされた PR が利用できない	リポジトリにスタックされた PR が有効になっていません。インタラクティブモードでは submit が通常の（スタックされていない）PR を作成することを提供します

既知の制限

1. スタックは厳密に線形です。 ブランチ化スタック（単一の親に複数の子がある）はサポートされていません。各ブランチは正確に 1 つの親と最大 1 つの子を持ちます。並列のワークストリームが必要な場合は、別のスタックを使用してください。
2. スタック曖昧性をバイパスできません。 現在のブランチが複数のスタックのトランクである場合、コマンドはコード 6 で終了します。最初に共有されていないブランチをチェックアウトしてください。
3. 複数のリモートは --remote または設定が必要です。 複数のリモートが構成されている場合、--remote <name> を渡すか、push, sync, または rebase を実行する前に git 設定で remote.pushDefault を設定してください。
4. PR のマージ: CLI からスタックされた PR をマージすることはまだサポートされていません。ユーザーに PR URL をブラウザで開いて PR をマージするよう指示してください。
5. リモートスタックチェックアウトには PR 番号が必要です。 ブランチ名での checkout はローカルでトラッキングされたスタックでのみ機能します。GitHub からスタックをプルするには PR 番号（例: gh stack checkout 123）を使用してください。
6. PR タイトルと本体は自動生成されます。 submit 中にカスタム PR タイトルまたは本体を設定するフラグはありません。タイトルと本体はコミットメッセージおよびフッターから生成されます。作成後 gh pr edit を使用して PR タイトルと本体を変更してください。