stack

Stack

スカッシュマージに安全なスタック変更の修復には、ローカルの stack CLI を使用します。GitHub PR や GitLab MR がスカッシュマージされ、マージ済みブランチが削除されるリポジトリ向けに設計されています。このようなリポジトリでは、Git の系譜だけではスタックの意図を維持できません。

セットアップ

GitHub（gh 経由）と GitLab（glab 経由）で動作します。stack を実行する前に、対応する CLI をインストールして認証してください。

• origin から github.com と gitlab.com が自動検出されます。
• エンタープライズホスト：git config stack.codeHost github|gitlab（または STACK_CODE_HOST 環境変数で上書き）。
• カスタムトランク：git config stack.trunks dev,develop,main,master。
• スタックブロックから帰属リンクを削除：git config stack.blockLink false。

通常の編集とコミットには、引き続き通常の git を使用してください。スタックの意図の記録、確認、同期、マージ、取り消しに限って stack を使用します。

基本概念

dev
└─ stack-a  #101
   └─ stack-b  #102
      └─ stack-c  #103

スタックの意図は、スタックリンク（ブランチ、親、マージベースのアンカー、変更番号）として .git/stack/state.json に保存されます。変更を行うワークフローでは .git/stack/undo.json が書き込まれ、stack undo --apply で以前の状態を復元できます。これらのファイルを手動で編集しないでください。プレビューには stack sync、修正には stack sync --apply を実行してください。

基本的な流れ

スタックの構成が自動的に把握できるよう、適切なターゲットブランチを指定して PR を作成します。

gh pr create --base dev --head stack-a
gh pr create --base stack-a --head stack-b
stack sync              # preview inferred links and repairs
stack sync --apply      # record links, repair, retarget, refresh stack blocks

通常はこの流れを繰り返します。stack sync はプレビューを表示し、stack sync --apply は修復を実行します。親ブランチが変更された後や、スカッシュマージが完了した後に、これを繰り返してください。

同期では、子孫を修復する前に、ローカルで先行している親ブランチも公開します。ローカルでの修復が不要な親については、実際のプッシュ先を確認し、明示的なリースを使ってファストフォワード可能な変更のみを公開します。リモートの先端が分岐している場合や不明な場合は、再試行する前にフェッチして差分を解消してください。取り消しでは、ローカルの親ブランチにすでに存在していたコミットをロールバックせずに、リモートのみへの公開を復元します。また、予期しないリモートの変更を上書きすることはありません。

コマンド

• stack status — 現在のスタックグラフを表示します（バックアップは非表示。コードホストが利用可能な場合は、オープン中の変更のタイトルも表示します）。
• stack skill — AI エージェントが参照できるよう、このスキルを出力します。
• stack doctor — 変更を加えずに、Git、コードホストへのアクセス、スタックのメタデータ、トランク、取り消しジャーナルの状態を確認します。
• stack track <branch> --onto <parent> — ターゲットブランチからスタックの意図を把握できない場合に限り、手動で記録します。
• stack sync [branch] — 推定したリンクと修復内容をプレビューします（変更は加えません）。ブランチを指定しない場合は、現在のスタックが対象になります。
• stack sync --apply [branch] — リンクを推定し、古いリンクを削除して、子孫を修復し、変更のターゲットを変更し、スタックブロックを更新して、ツリーの概要を表示します。
• stack sync --apply --keep-going — 独立したスタックを個別に処理し、成功と失敗を報告します。失敗があれば、ゼロ以外の終了コードで終了します。
• stack merge [branch] — ルートのマージと子孫の修復をドライランします。現在のブランチからルートを推定します。
• stack merge --apply — 子の変更のターゲットを変更し、ルートをスカッシュマージして、子孫を修復します。
• stack merge --auto — 子のターゲットを変更し、コードホストで自動マージを有効にして完了を待ってから、子孫を修復します。
• stack merge --auto --through <branch-or-change> — ターゲットがマージされるまで、ルートを一度に 1 つずつ自動マージします。
• stack history — 最後に適用された修復ジャーナルを表示します。
• stack undo — 最後に適用された変更の復元をドライランします。
• stack undo --apply — ブランチの先端、変更のターゲット、スタックのメタデータを復元します。

スタックブロック

stack sync --apply と stack merge --apply/--auto は、オープン中の各変更の説明にある決まった形式のブロックを更新します。

### [Stack](https://github.com/kitlangton/stack)

1. #101
2. #102
3. **#103** 👈 current

以前の項目はマージ済みの履歴です。現在の変更は太字で 👈 current と表示されます。GitHub では #123、GitLab では !123 - Title が使われます。

安全ルール

• 単独の stack sync は、ブランチ、変更、スタックのメタデータを変更しません。
• stack merge はデフォルトでドライランです。
• 変更を伴うコマンドには --apply が必要です（merge --auto を除きます。これはコードホストを待ち、ルートがマージされた後に修復します）。
• トランクブランチ（dev、main、master、または設定済みのトランク）は変更しません。
• リベースの前に、ツールはローカルバックアップブランチを作成します。
• クリーンな兄弟ワークツリーが、修復またはクリーンアップ対象のブランチを所有している場合があります。変更がある兄弟の所有者がいる場合は、変更を加える前に処理を中止します。
• リプレイに失敗した場合、ツールはチェリーピックを中止して元のブランチを復元し、バックアップと取り消しジャーナルを保持したうえで、stack sync --apply を再実行する前に修復すべきブランチを知らせます。
• 出力が不明瞭な場合は、適用する前に stack status、stack history、またはコマンドのヘルプを確認してください。