av-cli

Aviator CLI（av），用于堆叠 PR

你正在帮助用户使用 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

重要：始终使用 cat 读取 av.db，绝不要使用 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 会跳过重新堆叠并破坏堆栈。

绝不要将 --no-edit 传给 av commit --amend。 该标志不存在——不编辑本来就是默认行为。直接使用 av commit --amend 即可。

绝不要使用 gh pr edit --body 更新由 av 管理的 PR 描述。 它会完全替换正文，并覆盖 av 嵌入正文末尾、用于跟踪堆栈的 `` 块；移除该块会在不提示的情况下破坏堆栈跟踪。请改用 av pr --title "..." --body "..."；它适用于现有 PR，并会保留元数据块。

绝不要使用 av pr --edit。 它会打开 Agent 无法操作的编辑器。请直接使用 av pr --title "..." --body "..."——它既可创建新的 PR，也可更新现有 PR，且不会打开编辑器。

检测与设置

检查 av 是否已初始化：运行 git rev-parse --git-common-dir，然后运行 test -f <git-common-dir>/av/av.db

• 如果文件存在，则仓库已初始化 av。使用 av 命令进行分支和 PR 操作。
• 如果文件不存在，询问用户是否要使用 av init 进行初始化。
• 详细的命令参考请参阅 reference.md。
• 工作流示例请参阅 examples.md。
• 运行 av <command> --help 或 man av-<command> 获取最新的命令文档。

非交互模式（Agent 和自动化）

许多 av 命令默认会显示 Agent 无法使用的交互式 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 和手动操作

推荐的 Agent 工作流：

# 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 信息时始终使用此 URL，而不只是编号）
• 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 会自动设置正确的基分支（父分支，而不是主干分支）。
3. 协同同步：av sync 会通过一条命令获取、变基并推送所有分支。

堆叠式 PR 的工作方式

每个 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、后端、前端）可以审查相关部分。审查期间如果数据库架构发生变化，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	将分支中的所有提交压缩为一个

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 推送更改并跨整个堆栈进行变基
• 使用 gh pr edit --body "..." 更新由 av 管理的 PR 描述 → 改用 av pr --title "..." --body "..."；gh pr edit --body 会移除 av 元数据块，破坏堆栈跟踪
• 仅为了推送一个独立分支而运行 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 会执行获取、变基和推送的完整流程，可能需要 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 初始化后，所有操作都使用 av——即使只有一个 PR。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——这是推送单个独立分支最简单的方式。av sync 会获取最新状态、执行变基，并推送整个堆栈——在堆栈中工作时使用它可让所有分支保持同步，也可在 PR 合并后用于清理。

重要行为

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”，务必显示完整且可点击的 URL，例如 https://github.com/org/repo/pull/123。