graphite-stacks

Graphite スタック

Graphite CLI を使用した、スタック型 PR によるトランクベース開発。

<when_to_use>

• ブランチスタックの作成または管理
• スタック型 PR の送信
• ブランチの関係の再編成
• スタック全体にわたる PR フィードバックへの対応
• スタック破損からの復旧
• あらゆる gt コマンドの使用

</when_to_use>

基本原則

gt コマンドのみを使用してください。 git と gt を混在させると、同期の問題やスタックの分岐が発生します。唯一の例外は、ステージングのための git add です（または -a フラグを使用してください）。

こちらを使う、あちらではない

タスク	こちら	あちらではない
ブランチの作成	gt create 'name' -am "msg"	git checkout -b name
変更のコミット	gt modify -acm "msg"	git commit -m "msg"
リモートへのプッシュ	gt submit	git push
スタックのリベース	gt restack	git rebase
スタックの表示	gt status または gt ls	git log --graph
ブランチの切り替え	gt checkout	git checkout
コミットの修正	gt modify -a	git commit --amend
複数 PR のフィードバック	gt top && gt absorb -a	コミットを手動でチェリーピック

スタックのライフサイクル

Create stack → Implement features → Submit PRs → Address feedback → Merge
     │              │                  │               │            │
     ▼              ▼                  ▼               ▼            ▼
 gt create     gt modify -acm     gt submit      gt absorb     gt sync

スタックの作成

# New branch with staged changes
gt create 'feature/step-1' -am "feat: first step"

# Continue stacking
gt create 'feature/step-2' -am "feat: second step"
gt create 'feature/step-3' -am "feat: third step"

# Insert branch between current and child
gt create 'feature/step-1.5' --insert -am "feat: inserted step"

ナビゲーション

コマンド	動作
gt up	スタックを上に移動（子に向かって）
gt down	スタックを下に移動（親に向かって）
gt top	スタックの先頭にジャンプ
gt bottom	スタックの末尾にジャンプ
gt checkout	対話形式のブランチ選択

ブランチの変更

# Amend current branch (stages all)
gt modify -a

# New commit within same branch
gt modify -acm "fix: address review feedback"

# Commit to a different branch in the stack
git add path/to/file.ts
gt modify --into target-branch -m "feat: add file"

必ず行う:

• 新しいブランチには gt create を使用する
• コミットには gt modify を使用する
• プッシュには gt submit を使用する
• 親の変更後には gt restack を使用する
• 不明な場合は gt status を確認する

決して行わない:

• git commit/push/rebase を gt ワークフローと混在させる
• スタックの状態を理解せずに強制プッシュする
• git rebase -i を使用する（Graphite のメタデータが破損します）

レビューフィードバックへの対応

単一の PR: ブランチに移動し、直接変更する

gt checkout target-branch
gt modify -acm "fix: address review comment"
gt submit

スタック内の複数の PR: 先頭から absorb を使用する

gt top
git add .
gt absorb -a
gt submit --stack

Graphite はファイル履歴に基づいて、変更を正しいブランチに振り分けます。

スタックの再編成

# Move branch to different parent
gt move --onto new-parent

# Move specific branch
gt move --source branch-name --onto target

# After reorganization
gt restack

送信

# Current branch + downstack
gt submit

# Entire stack
gt submit --stack

# Non-interactive (automation)
gt submit --no-interactive

スタックの可視化

# JSON with parent relationships (preferred for scripts)
gt status

# Visual tree
gt ls

# Recent history
gt log

同期とメンテナンス

# Pull trunk, rebase stacks, clean merged
gt sync

# Rebase branches onto updated parents
gt restack

# Undo last gt operation
gt undo

問題が発生した場合

スタック破損の症状:

• ブランチが親子ではなく兄弟として表示される
• PR に誤ったファイルが含まれる
• gt status が予期しない構造を表示する

手順ごとの復旧手順については、recovery.md を参照してください。

• commands.md - コマンドのクイックリファレンス
• recovery.md - スタック破損からの復旧