Zenn
📚

GraphiteによるStacking手法について

に公開
Git
Graphite
stacking
tech

Claudeにgtコマンドを試してもらいつつ、gitとのトレードオフについて質問した回答から生成してあります。

概要

Graphite (gt) は、GitHubでのコード作成とレビューのライフサイクル全体を簡素化するツールです。特にPRスタッキング（プルリクエストを積み重ねる機能）を可能にし、小さく集中した変更を効率的に管理できます。

バージョン

  • 現在のバージョン: 1.6.6
  • インストール場所: /opt/homebrew/bin/gt

基本概念

用語定義

  • stack: プルリクエストのシーケンス。各PRが親PRの上に構築される
    • 例: main ← PR "add API" ← PR "update frontend" ← PR "docs"
  • trunk: スタックがマージされるブランチ（通常はmain）
  • downstack: スタック内の下位PR（祖先）
  • upstack: スタック内の上位PR（子孫）

セットアップ

認証

  1. https://app.graphite.dev/settings/cli を開く
  2. 新しい認証トークンを作成
  3. 生成されたコマンドを実行: gt auth --token <token>

初期化

gt init  # リポジトリでGraphiteを初期化

コアコマンド

ワークフロー関連

コマンド 説明 エイリアス
gt create [name] 新しいブランチを作成し、変更をコミット c
gt modify 現在のブランチを修正し、自動的に上位ブランチをリベース m
gt submit スタックをGitHubにプッシュし、PRを作成/更新 s
gt sync 全ブランチを同期し、マージされたブランチの削除を促す -

ナビゲーション

コマンド 説明 エイリアス
gt checkout [branch] ブランチを切り替え（インタラクティブセレクター付き） co
gt up [steps] 子ブランチに移動 u
gt down [steps] 親ブランチに移動 d
gt top スタックの最上位ブランチに移動 t
gt bottom スタックの最下位ブランチに移動 b

情報表示

コマンド 説明 エイリアス
gt log スタックのグラフィカル表示 l
gt info [branch] ブランチ情報を表示 -
gt parent 親ブランチを表示 -
gt children 子ブランチを表示 -

スタック管理

コマンド 説明 エイリアス
gt restack スタック内の全PRを最新の変更の上にリベース -
gt absorb ステージされた変更を関連するコミットに修正 ab
gt continue リベース競合で停止したGraphiteコマンドを継続 -
gt abort リベース競合で停止したGraphiteコマンドを中止 -

基本的なワークフロー

1. 最初のPRを作成

gt checkout main
# ファイルを編集
echo "new code changes" >> file.js
gt create --all --message "feat(api): Add new API method"
gt submit

2. スタックPRを作成

gt checkout  # インタラクティブにブランチを選択
# 追加の変更を行う
echo "frontend changes" >> frontend.js
gt create --all --message "feat(frontend): Update UI"
gt submit --stack

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

gt checkout first_pr_branch
# ファイルを修正
echo "fixed code" > file.js
gt modify --all  # コミットを修正し、上位ブランチを自動リベース
gt submit

4. 最新の変更を同期

gt sync  # mainから最新の変更を取得し、全スタックをリベース

便利な機能

インタラクティブチュートリアル

gt demo  # Graphiteワークフローの実践例を学習

ワークフローガイド

gt guide workflow  # 詳細なワークフローガイドを表示

設定オプション

gt config --help  # 設定オプションを確認

リソース

通常のGitとの違いとメリット

従来のGitワークフローとの比較

通常のGitワークフロー

# 従来の方法
git checkout main
git pull origin main
git checkout -b feature/new-api
# 作業...
git add .
git commit -m "Add new API"
git push origin feature/new-api
# PR作成をブラウザで手動実行

# さらに機能を追加する場合
git checkout main
git pull origin main
git checkout -b feature/frontend-update
# 作業...
git add .
git commit -m "Update frontend"
git push origin feature/frontend-update
# 別のPR作成をブラウザで手動実行

Graphite (gt) ワークフロー

# Graphiteの方法
gt checkout main
gt create --all --message "Add new API"
gt submit

# 依存する機能を同じスタックに追加
gt create --all --message "Update frontend to use new API"
gt submit --stack

主要な違い

項目 通常のGit Graphite (gt)
ブランチ管理 手動でブランチ作成・切り替え 自動ブランチ作成・管理
PR作成 ブラウザで手動作成 コマンドラインから自動作成
依存関係 独立したPR PRスタッキングで依存関係を明示
リベース 手動でgit rebase実行 自動リベース（gt restack）
コンフリクト解決 複雑なリベース手順 ガイド付きコンフリクト解決
ブランチ同期 手動で各ブランチを更新 gt syncで一括同期

Graphiteの具体的なメリット

1. 開発効率の向上

  • ブロッキングの解消: レビュー待ちの間も依存する機能を並行開発
  • 小さなPR: 大きな変更を小さく分割して、レビューを高速化
  • 自動化: ブランチ管理、PR作成、リベースが自動化

2. コードレビューの改善 

# 従来: 大きな変更を一つのPRで
git commit -m "Implement user management system (500 lines changed)"

# Graphite: 小さく分割された変更
gt create -m "Add user model and database schema"      # 50行
gt create -m "Add user authentication endpoints"       # 80行  
gt create -m "Add user management UI components"       # 120行
gt create -m "Add user management integration tests"   # 60行

メリット:

  • レビュワーの負荷軽減
  • バグの早期発見
  • より詳細なフィードバック
  • 段階的なマージが可能

3. リベース・コンフリクト解決の簡素化 

# 従来のGitでスタックをリベース
git checkout feature-1
git rebase main
git checkout feature-2  
git rebase feature-1
git checkout feature-3
git rebase feature-2
# 各ステップでコンフリクトが発生する可能性

# Graphiteでスタックをリベース  
gt sync  # 全スタックを一括で最新のmainにリベース

4. チーム開発での優位性

  • 透明性: スタック内の依存関係が明確
  • 並行作業: 複数の開発者が同じスタックで作業可能
  • 段階的マージ: スタックの一部だけをマージすることも可能

5. エラー回復の簡素化 

# リベース中にエラーが発生した場合
gt abort    # 操作を中止
gt continue # コンフリクト解決後に継続

実際の使用場面での比較

シナリオ: 新機能の実装

要件: ユーザー管理システムの実装（API + フロントエンド + テスト）

従来のGitアプローチ:

  1. 大きなPRを作成（200-500行の変更）
  2. レビューに時間がかかる
  3. フィードバック対応で大幅な修正が必要
  4. 他の開発者はマージまで待機

Graphiteアプローチ:

gt create -m "Add user model and validation"     # PR #1 (50行)
gt create -m "Add user authentication API"       # PR #2 (80行, #1に依存)
gt create -m "Add user management UI"            # PR #3 (120行, #2に依存)  
gt create -m "Add integration tests"             # PR #4 (60行, #3に依存)
gt submit --stack

結果:

  • PR #1は即座にレビュー・マージ可能
  • 他の開発者はPR #1のマージを待たずに並行作業
  • 各PRは小さく、レビューが高速
  • 問題があってもスタックの一部だけ修正

トレードオフと導入判断

通常のGitでもスタッキングは可能

通常のgitでもPRスタッキングは実現できます：

# 通常のgitでのスタッキング
git checkout main
git checkout -b feature-1
# 作業...
git commit -m "Add API"

git checkout -b feature-2  # feature-1から分岐
# 作業...
git commit -m "Add UI"

git checkout -b feature-3  # feature-2から分岐
# 作業...
git commit -m "Add tests"

Graphiteのトレードオフ

デメリット・課題

  1. 学習コスト

    • 新しいツールとワークフローの習得が必要
    • チーム全体での導入・教育コスト

  2. 外部依存性

    • Graphiteサービスへの依存
    • サービス障害時の作業停止リスク
    • 認証トークンの管理が必要

  3. 複雑性の増加

    # リベースコンフリクト発生時の比較

# 通常のGit: 各ブランチで個別に解決
git checkout feature-1; git rebase main      # コンフリクト1
git checkout feature-2; git rebase feature-1 # コンフリクト2  
git checkout feature-3; git rebase feature-2 # コンフリクト3

# Graphite: 自動化されているが、途中で止まると複雑
gt sync  # 全スタック一括処理、失敗時はより複雑な状況

  4. チーム導入の課題

    • 全メンバーが同じツールを使用する必要
    • 既存ワークフローからの移行コスト

メリット

  1. 作業効率の大幅向上
  2. 人的ミスの削減（自動化による）
  3. 統一されたワークフロー
  4. PR管理の簡素化

適用場面による判断基準

Graphiteの導入を推奨する場面

✅ 以下の条件に当てはまる場合：

  • 頻繁なスタッキング作業（週に複数回）
  • 中〜大規模チーム（5人以上）
  • PR作成・管理の自動化を重視
  • リベース操作に不慣れなメンバーがいる
  • 統一されたワークフローを求める
  • レビューサイクルの高速化が必要

通常のGitが適している場面

❌ 以下の条件に当てはまる場合：

  • シンプルな開発フローで十分
  • 小規模チーム（2-4人）
  • 既存ワークフローが確立済み
  • 外部依存を避けたい
  • スタッキングの頻度が低い
  • 学習コストを避けたい

結論

Graphiteは効率化のオプションであり、必須ツールではありません。スタッキング頻度、チーム規模、複雑性許容度、学習コストを総合的に判断して導入を決定することが重要です。

特に、既存のワークフローで問題を感じていない場合は、無理に導入する必要はありません。一方で、頻繁なスタッキング作業やチーム規模の拡大により効率化が必要な場合は、非常に有効なツールとなります。

まとめ

Graphite CLIは、PRスタッキングによる効率的なコード開発とレビューを可能にする強力なツールです。従来のGitワークフローを簡素化し、小さな変更を積み重ねることで、より迅速で焦点を絞った開発プロセスを実現します。ただし、導入には学習コストや外部依存性などのトレードオフがあるため、チームの状況に応じて慎重に判断することが重要です。

Discussion