using-git-spice

git-spice の使い方

概要

git-spice（gs）は、積み重ねた Git ブランチとその変更リクエストを管理する CLI ツールです。

基本原則：git-spice はブランチ間の関係（スタック）を追跡し、依存するブランチのリベースと送信を自動化します。

主な概念

スタックの用語：

• スタック：現在のブランチにつながるすべてのブランチ（アップスタックとダウンスタックの両方）
• アップスタック：現在のブランチの上に構築されたブランチ（子ブランチとその子孫）
• ダウンスタック：現在のブランチからトランクまでの下位ブランチ（親ブランチとその祖先）
• トランク：メインの統合ブランチ（通常は main または master）

スタックの例：

┌── feature-c     ← upstack from feature-b
├── feature-b     ← upstack from feature-a, downstack from feature-c
├── feature-a     ← downstack from feature-b
main (trunk)

feature-b にいる場合：

• アップスタック：feature-c
• ダウンスタック：feature-a、main
• スタック：feature-a、feature-b、feature-c

クイックリファレンス

タスク	コマンド	メモ
リポジトリを初期化	gs repo init	リポジトリごとに一度だけ必要です。トランクブランチを設定します。
スタックブランチを作成	gs branch create <name>	現在のブランチの上にブランチを作成します。短縮形は gs bc です。
スタックを表示	gs log short	現在のスタックを表示します。詳細を確認するには gs ls または gs log long（gs ll）を使います。
スタックを PR として送信	gs stack submit	スタック全体を送信します。短縮形は gs ss です。
アップスタックのみ送信	gs upstack submit	現在のブランチと子ブランチを送信します。短縮形は gs us s です。
ダウンスタックのみ送信	gs downstack submit	現在のブランチと、トランクまでの親ブランチを送信します。短縮形は gs ds s です。
スタック全体をリベース	gs repo restack	追跡対象のすべてのブランチを、それぞれのベースにリベースします。
現在のスタックをリベース	gs stack restack	現在のブランチのスタックをリベースします。短縮形は gs sr です。
アップスタックをリベース	gs upstack restack	現在のブランチと子ブランチをリベースします。短縮形は gs us r です。
ブランチを新しいベースに移動	gs upstack onto <base>	現在のブランチとアップスタックを新しいベースに移動します。
リモートと同期	gs repo sync	最新の変更を取り込み、マージ済みのブランチを削除します。
既存のブランチを追跡	gs branch track [branch]	ブランチを git-spice の追跡対象に追加します。
ブランチを削除	gs branch delete [branch]	ブランチを削除し、子ブランチをリスタックします。短縮形は gs bd です。

コマンドの短縮形： ほとんどのコマンドには短縮形があります。すべての短縮形を確認するには gs --help を使います。

よくあるワークフロー

これらのワークフローは、単一リポジトリのシナリオに適用されます。複数のリポジトリにまたがる機能については、以下のマルチリポジトリのワークフローを参照してください。

ワークフロー 1：スタックを作成して送信する

# One-time setup
gs repo init
# Prompt asks for trunk branch (usually 'main')

# Create stacked branches
gs branch create feature-a
# Make changes, commit with git
git add . && git commit -m "Implement A"

gs branch create feature-b  # Stacks on feature-a
# Make changes, commit
git add . && git commit -m "Implement B"

gs branch create feature-c  # Stacks on feature-b
# Make changes, commit
git add . && git commit -m "Implement C"

# View the stack
gs log short

# Submit entire stack as PRs
gs stack submit
# Creates/updates PRs for all branches in stack

ワークフロー 2：レビュー後にブランチを更新する

# You have feature-a → feature-b → feature-c
# Reviewer requested changes on feature-b

git checkout feature-b
# Make changes, commit
git add . && git commit -m "Address review feedback"

# Rebase upstack (feature-c) on updated feature-b
gs upstack restack

# Submit changes to update PRs
gs upstack submit
# Note: restack only rebases locally, submit pushes and updates PRs

重要：feature-c を手動でリベースしないでください！ gs upstack restack を使ってスタックの関係を維持します。

ワークフロー 3：上流のマージ後に同期する

# feature-a was merged to main
# Need to update feature-b and feature-c

# Sync with remote (pulls main, deletes merged branches)
gs repo sync

# Restack everything on new main
gs repo restack

# Verify stack looks correct
gs log short

# Push updated branches
gs stack submit

重要：feature-c を main にリベースしないでください！ feature-a のマージ後：

• feature-b は（新しいベースである）main にリベースされます
• feature-c は（依存関係を維持するため）feature-b にリベースされます

Git と git-spice の使い分け

次の操作には git-spice を使います：

• スタック内にブランチを作成する：gs branch create
• スタックをリベースする：gs upstack restack、gs repo restack
• PR を送信する：gs stack submit、gs upstack submit
• スタック構造を表示する：gs log short
• ブランチを削除する：gs branch delete（子ブランチをリスタックします）

次の操作には git を使います：

• 変更を加える：git add、git commit
• 状態を確認する：git status、git diff
• コミット履歴を表示する：git log
• 個々のブランチを操作する：git checkout、git switch

スタックブランチに git rebase を直接使わないでください — 関係を維持するには git-spice の restack コマンドを使います。

よくある間違い

間違い	問題点	正しい方法
親ブランチのマージ後に、子ブランチを trunk にリベースする	スタックの関係が崩れ、コンフリクトが発生します	gs repo sync && gs repo restack を使用します
変更後に git push --force を使用する	git-spice の追跡を迂回します	gs upstack submit または gs stack submit を使用します
git rebase で手動リベースする	git-spice はリベースを追跡しません	gs upstack restack または gs stack restack を使用します
間違ったブランチで gs stack submit を実行する	意図しないブランチを送信する可能性があります	まず gs log short を実行して、スタックに含まれるものを確認します
gs repo init を忘れる	コマンドが分かりにくいエラーで失敗します	リポジトリごとに一度、gs repo init を実行します
upstack のつもりで stack を使用する	ダウンスタックのブランチ（親ブランチ）も送信されます	現在のブランチと子ブランチだけを送信するには upstack を使用します
restack が自動的に実行されると思い込む	コミット後にスタックがずれることがあります	変更後に gs upstack restack を明示的に実行します

注意が必要なケース — ドキュメントを確認してください

• スタック、アップスタック、ダウンスタックの対象範囲が分からない
• 追跡対象のブランチで git rebase を実行しようとしている
• どの送信コマンドを使えばよいか分からない
• 「not tracked」エラーが発生する

不明な場合は、gs <command> --help を実行して詳しい使い方を確認してください。

認証とセットアップ

初回セットアップ：

# Authenticate with GitHub/GitLab
gs auth login
# Follow prompts for OAuth or token auth

# Initialize repository
gs repo init
# Sets trunk branch and remote

# Verify setup
gs auth status

コンフリクトへの対処

gs upstack restack または gs repo restack でコンフリクトが発生した場合：

1. 標準的な Git のワークフロー（git status、ファイルの編集、git add）でコンフリクトを解決します
2. git rebase --continue で続行します
3. git-spice が残りのブランチのリスタックを再開します
4. 解決後、gs upstack submit を実行して変更をプッシュします

リスタックを中止する必要がある場合は、復旧方法について gs --help を確認してください。

複数リポジトリでのワークフロー

リポジトリごとのスタックの制限

Git-spice は一度に 1 つのリポジトリのみを操作します。複数のリポジトリにまたがる機能開発では：

• 各リポジトリには独立したスタックがあります
• リポジトリをまたぐ直線的なスタックは作成できません
• ブランチはそれぞれのリポジトリ内にとどまります

複数リポジトリの PR の送信

複数のリポジトリにまたがる機能では、フェーズの順序に従って PR を送信します：

フェーズ順の送信：

# Phase 1 repos first (foundation)
cd shared-lib
gs stack submit
cd ..

# Phase 2 repos second
cd backend
gs stack submit
cd ..

# Phase 3 repos last (depends on earlier phases)
cd frontend
gs stack submit
cd ..

フェーズの順序が重要な理由：

• フェーズ 1 の変更（例：共有型）は、フェーズ 2 の利用側をマージする前にマージする必要があります
• 依存関係が不足してビルドが壊れるのを防ぎます
• 開発時の実行順序に沿っています

複数リポジトリのスタックの可視化

すべてのリポジトリのスタックを表示します：

# From workspace root
for repo in backend frontend shared-lib; do
  echo "=== $repo ==="
  cd $repo && gs log short && cd ..
done

複数リポジトリの同期

PR のマージ後、すべてのリポジトリを同期します：

# From workspace root
for repo in backend frontend shared-lib; do
  echo "Syncing $repo..."
  cd $repo && gs repo sync && cd ..
done

リポジトリ間の依存関係の調整

リポジトリ A の PR がリポジトリ B の PR に依存している場合：

1. 先にリポジトリ B の PR をマージします
2. マージされた変更を使用するよう、リポジトリ A を更新します
3. その後、リポジトリ A の PR をマージします

例：

shared-lib: PR for new types
  ↓ (merge first)
backend: PR using new types
  ↓ (merge second)
frontend: PR using backend API
  ↓ (merge third)

その他のリソース

• CLI の全リファレンス：gs --help
• コマンド固有のヘルプ：gs <command> --help
• 設定：gs config --help
• 公式ドキュメント：https://abhinav.github.io/git-spice/