av-cli

Stacked PR 向け Aviator CLI（av）

Aviator の av CLI ツールを使って、スタックされたプルリクエストを扱うユーザーを支援します。

重要：git ディレクトリ内（git rev-parse --git-common-dir で確認できます）の av/av.db ファイルを、直接変更しないでください。 この JSON ファイルは av コマンドによって管理されています。スタック構造の確認のために読み取ることはできますが、変更には必ず av CLI コマンドを使用してください。

最初の手順（必ず実行してください）

av を使うときは、ブランチ構造を把握するため、必ず最初に git の共通ディレクトリにある av/av.db を読み取ってください。 この JSON ファイルが信頼できる唯一の情報源です。

git rev-parse --git-common-dir

次に、その結果を使って DB ファイルを読み取ります。

cat <git-common-dir>/av/av.db

重要：av.db の読み取りには必ず cat を使用してください。Read ツールは絶対に使わないでください。 .db 拡張子のため、Read はこのファイルを誤ってバイナリとして扱います。

ヒント： git branch --show-current で現在のブランチを特定し、そのブランチのエントリーを av.db で確認すると、スタック内の位置と PR 情報を把握できます。

構造の把握に av tree を使わないでください。 視覚的な出力は誤解を招きます。av.db のみを使用してください。

重要なルール

git commit や git push を直接使わないでください。 コミットには必ず av commit を使い、プッシュには av pr（自動でプッシュします）または av sync --push=yes --prune=yes を使ってください。git を直接使うと、スタックの再構成が省略され、スタックが壊れます。

av commit --amend に --no-edit を付けないでください。 このフラグは存在しません。no-edit はデフォルトの動作です。av commit --amend をそのまま使ってください。

av が管理する PR の説明を更新するために、gh pr edit --body を使わないでください。 これは本文全体を置き換え、スタックを追跡するために av が本文末尾に埋め込む `` ブロックを上書きします。このブロックが削除されると、気付かないうちにスタックの追跡が壊れます。代わりに av pr --title "..." --body "..." を使ってください。既存の PR にも使用でき、メタデータブロックは保持されます。

av pr --edit を使わないでください。 エージェントが操作できないエディターが開きます。av pr --title "..." --body "..." を直接使ってください。エディターを開かずに、新しい PR の作成にも既存の PR の更新にも使えます。

検出とセットアップ

av が初期化済みか確認するには： git rev-parse --git-common-dir を実行し、続けて test -f <git-common-dir>/av/av.db を実行します。

• ファイルが存在する場合、リポジトリは av で初期化済みです。ブランチや PR の操作には av コマンドを使用してください。
• ファイルが存在しない場合、av init で初期化するかユーザーに確認してください。
• 詳細なコマンドリファレンスについては、reference.md を参照してください。
• ワークフローの例については、examples.md を参照してください。
• 最新のコマンドドキュメントを確認するには、av <command> --help または man av-<command> を実行してください。

非対話モード（エージェントと自動化）

多くの av コマンドは、エージェントが使用できない対話型 TUI プロンプトをデフォルトで表示します。必ず以下の非対話フラグを使用してください。

重要な構文上の注意： フラグの値の指定には、スペースではなく =（等号）が必要です。--push=yes は動作しますが、--push yes は動作しません。

コマンド	対話型の動作	非対話フラグ
av sync	プッシュとプルーンの確認を求めます	--push=yes（または =no）、--prune=yes（または =no）
av pr（新しい PR）	タイトルと本文を編集するエディターが開きます	--title "..." --body "..."
av pr（既存の PR）	プロンプトは表示されず、そのままプッシュします	引数なしの av pr はプッシュします。説明も更新する場合は --title／--body を追加します（エディターは開かず、av のメタデータブロックを保持します）
av switch（引数なし）	ブランチ選択画面が開きます	av switch <branch-name>
av adopt（引数なし）	対話型のブランチ選択を行います	対象ブランチで av adopt --parent <parent> を実行します
av split-commit	対話型の分割箇所選択画面が開きます	非対話モードはありません。 代わりに git reset と手動のステージングを使ってください
av reorder	リベース計画用のエディターが開きます	非対話モードはありません。 代わりに av reparent と手動操作を使ってください

推奨するエージェントのワークフロー：

# Creating a new PR:
av commit -A -m "message"
av pr --title "Title" --body "Body"  # pushes the branch and creates the PR

# Pushing updates to an existing PR (single branch, not in a stack):
av commit -A -m "message"
av pr  # no args needed — just pushes the branch and updates the PR, no editor prompt

# Pushing updates when working in a stack (syncs the entire stack):
av commit -A -m "message"
av sync --push=yes --prune=yes

スタック構造を理解する

git rev-parse --git-common-dir を実行してから、cat <result>/av/av.db を実行すると、ブランチ間の関係を確認できます。形式は次のとおりです。

{
  "branches": {
    "feature-api": {
      "name": "feature-api",
      "parent": { "name": "master", "trunk": true },
      "pullRequest": {
        "number": 123,
        "permalink": "https://github.com/org/repo/pull/123"  // USE THIS URL
      }
    },
    "feature-ui": {
      "name": "feature-ui",
      "parent": { "name": "feature-api", "head": "abc123" }
    }
  }
}

主なフィールド：

• parent.trunk: true → ブランチは main/master から直接派生しています（スタックされていません）
• parent.name + parent.head → ブランチは別のブランチの上にスタックされています
• pullRequest.permalink → PR の完全な URL（PR 情報を表示するときは、番号だけでなく必ずこれを使用してください）
• excludeFromSyncAll: true → ブランチは av sync --all の対象外です

構造の読み取り方： 各ブランチの parent.name から、そのブランチの派生元がわかります。親子関係をたどってツリーを作成します。trunk: true のブランチは、すべて独立したルートです。

主な概念

スタックとは？

スタックとは、各ブランチがその前のブランチを基に構築される、依存関係のあるブランチの連鎖です。

main
 └── feature-auth (PR #1: adds auth)
      └── feature-login (PR #2: adds login, depends on auth)
           └── feature-logout (PR #3: adds logout, depends on login)

av を使う理由

1. 自動リベース：スタックの途中にあるブランチを更新すると、av がすべての子ブランチをリベースします。
2. 適切な PR のベース：av pr は、正しいベースブランチ（trunk ではなく親ブランチ）を自動的に設定します。
3. 一括同期：av sync は、1 つのコマンドで、すべてのブランチをフェッチ、リベース、プッシュします。

スタックされた PR の仕組み

各 PR に表示されるのは、累積した trunk との差分ではなく、その PR 固有の差分（親ブランチに対する変更）だけです。これにより、コードレビューの対象を絞り、管理しやすくできます。

よくあるユースケース：フルスタック機能

最も一般的なワークフローは、複数のレイヤーにまたがる機能を構築することです。

main
 └── add-feature-db       (DB schema/migrations)
      └── add-feature-service  (Backend service logic)
           └── add-feature-api      (REST/GraphQL endpoints)
                └── add-feature-ui       (Frontend components)

各レイヤーを、それぞれ対象を絞った PR にします。異なる専門知識を持つレビュアー（DBA、バックエンド、フロントエンド）が、担当する部分をレビューします。レビュー中に DB スキーマが変更された場合も、av sync が更新をスタック全体に自動で反映します。

基本コマンド

ブランチ管理

コマンド	目的
av branch <name>	現在のブランチの上にスタックされた新しいブランチを作成する
av branch --parent <parent> <name>	指定した親を持つブランチを作成する
av branch -m <new-name>	現在のブランチの名前を変更する
av adopt --parent <parent>	現在のブランチを指定した親とともにスタックに追加する
av adopt --remote <branch>	リモートブランチをフェッチして追加する（例：同僚の作業）
av reparent --parent <new-parent>	現在のブランチを別の親に移動する
av orphan	現在のブランチを av の管理対象から外す

av adopt --remote は特に便利です。同僚のブランチ（または、まだローカルで追跡していないリモートブランチ）を取り込み、正しいスタック関係を自動的に設定できます。ブランチをフェッチし、その親ブランチの連鎖を検出して、ローカルの av の状態に統合します。これは、手動でチェックアウトして追加するよりもはるかに確実です。

コミット

コマンド	目的
av commit -m "message"	コミットし、子ブランチを自動でリスタックします
av commit -a -m "message"	変更されたファイルをステージしてコミットします
av commit -A -m "message"	すべてのファイル（未追跡ファイルを含む）をステージしてコミットします
git add <files> && av commit -m "msg"	指定したファイルをステージしてからコミットします
av commit --amend	最後のコミットを修正し、子ブランチをリスタックします
av split-commit	現在のコミットを対話形式で分割します（非対話モードはありません）
av squash	ブランチのすべてのコミットを1つにまとめます

av commit と git commit の主な違い：

• --amend はデフォルトで既存のメッセージを再利用します。--no-edit フラグはありません。これがデフォルトの動作です。
• --edit は、修正時に明示的にエディターを開きます（git のデフォルトとは逆です）。
• -a は git の -a と同じ動作です（追跡対象の変更・削除済みファイルのみをステージします）。
• -A / --all-changes は av 固有で、未追跡ファイルを含むすべてのファイルをステージします（git には同等の単一フラグはありません）。

選択的なステージング： -a と -A はすべてをステージします（追跡対象のファイル、またはすべてのファイル）。特定のファイルのみをコミットするには、先に git add <files> でステージし、その後 -a / -A を付けずに av commit を実行します。新しいコミットと修正コミットのどちらにも使えます。

よくある間違い：

• git commit -m "message" → 代わりに av commit -m "message" を使います
• git push → PR を作成する場合は av pr を使います（自動でプッシュされます）。変更をプッシュしてスタック全体でリベースする場合は av sync --push=yes --prune=yes を使います
• av 管理の PR の説明を更新するために gh pr edit --body "..." を使う → 代わりに av pr --title "..." --body "..." を使います。gh pr edit --body は av メタデータブロックを削除し、スタックの追跡に問題を起こします
• 単独のブランチを1つだけプッシュするために av sync --push=yes --prune=yes を使う → 代わりに av pr を使います（ただし、スタックで作業している場合は av sync が適切です）
• av commit --amend --no-edit → av commit --amend だけで十分です（no-edit がデフォルトで、フラグは存在しません）
• av pr の前後に av sync を実行する → 不要です。av pr が自動でプッシュします

プルリクエスト

コマンド	目的
av pr --title "Title" --body "Description"	現在のブランチの PR を作成・更新します
av pr --all	スタック全体の PR を作成・更新します
av pr --all --current	現在のブランチまでの PR を作成・更新します
av pr --draft	PR をドラフトとして作成します
av pr --edit	既存の PR のタイトルと本文を編集します

av pr は、PR の作成または更新前に、現在のブランチをリモートへ自動でプッシュします。事前に av sync や git push を実行する必要はありません。

注： 新しい PR を作成するときは、エディターのプロンプトを避けるために --title と --body を指定してください。既存の PR では、引数なしの av pr はプッシュのみを行います。対話なしで説明も更新するには、--title / --body を指定してください。いずれの場合も、av は本文末尾の `` ブロックを保持します。gh pr edit --body はこのブロックを削除するため、使わないでください。

同期

コマンド	用途
av sync	現在のスタックを取得、再スタックし、プッシュします
av sync --rebase-to-trunk	スタックのルートを最新の trunk にリベースします
av sync --all --rebase-to-trunk	すべてのスタックを最新の trunk にリベースします
av restack	子ブランチをローカルでリベースします（プッシュなし）
av fetch	GitHub から最新の状態を取得します

非対話モード： デフォルトでは、av sync は確認を求めます。明示的なフラグを使用してください（= 構文に注意してください。スペースを入れると動作しません）。

av sync --push=yes --prune=yes          # Sync current stack
av sync --all --push=no --prune=yes     # Sync all stacks (use after PRs are merged, ask user before pushing)

--push と --prune の両方を必ず指定してください。どちらかを省略すると TUI のプロンプトが表示されます。オプションは yes、no、ask（デフォルト）です。ほとんどの場合、--prune=yes を安全に使用できます。これは、PR がすでにマージされたローカルブランチのみを削除します。マージ済みのブランチをローカルに残しておく必要がある場合（例：参照用、または他のワークツリーでチェックアウトしている場合）は、--prune=no を使用してください。

タイムアウト： av sync は fetch + rebase + push のサイクルを実行するため、15〜30 秒以上かかることがあります。av sync コマンドには、少なくとも 60 秒のタイムアウトを設定してください。

移動

コマンド	用途
av switch	対話型ブランチ切り替えツール
av switch <branch>	指定したブランチに切り替えます
av next	子ブランチに移動します
av prev	親ブランチに移動します
av next --last	スタックの末尾に移動します
av prev --first	スタックのルートに移動します

コンフリクトの解決

リベースでコンフリクトが発生した場合：

1. エディターでコンフリクトを解決します
2. 解決したファイルを git add でステージングします
3. av sync --continue または av restack --continue で続行します

または、--abort で中止するか、--skip で問題のあるコミットをスキップします。

すべてのワークフローで av を使用する

リポジトリで av の初期化が完了したら、単一の PR であっても、すべての作業に av を使用してください。av はスタックを使わないワークフローでも非常に便利で、作業の一貫性を保てます。

シナリオ	コマンド
ブランチを作成する	av branch <name>
変更をコミットする	av commit -m "message"
新しい PR を作成する	av pr --title "Title" --body "Description"
更新をプッシュする（単一ブランチ）	av pr
スタックの一部の PR を作成する	av pr --all --current
スタック全体の PR を作成する	av pr --all
変更後に同期する	av sync --push=yes --prune=yes
PR がマージされた後	av sync --all --push=no --prune=yes
リモートブランチを取り込む	av adopt --remote origin/<branch>
ブランチを切り替える	av switch <branch>
親との差分を表示する	av diff

av pr と av sync の違い： av pr は現在のブランチをプッシュし、その PR を作成または更新します。単独のブランチを 1 つプッシュする最も簡単な方法です。av sync はスタック全体で fetch、rebase、push を行います。スタックを使って作業する際にすべてのブランチを同期する場合や、マージ後のクリーンアップに使用してください。

重要な動作

1. 常に av コマンドを使用します。単一の PR とスタックのどちらでも機能します。
2. av commit は子ブランチがある場合、自動的にスタックを再構成します。
3. ベースは av pr に設定させます。ベースブランチを手動で指定しないでください。
4. PR のマージ後、av sync --all --push=no --prune=yes を実行して、残りのブランチを整理し、リベースします。すべてのスタックをプッシュする前に、ユーザーに確認してください。
5. コミットや PR でスタックに言及しないでください。コミットメッセージ、PR タイトル、PR 本文で、スタック内の位置、親ブランチ、スタックの関係性に触れないでください。av ツールがこのメタデータを自動的に処理します。
6. PR の URL は必ず全体を表示します。PR 情報を表示するときは、av.db の permalink フィールドを使用してください。「PR #123」のような表示だけにせず、https://github.com/org/repo/pull/123 のようなクリック可能な完全な URL を必ず表示してください。