git-flow-next

git-flow-next

git-flow-next（https://git-flow.sh/，仓库 gittower/git-flow-next） 是本技能适用的 Gitflow CLI—— 不包括其他 git-flow 分支版本。

不要与已弃用的分支版本混淆

这两款旧工具也会提供 git-flow 二进制文件， 因此很容易混淆。

• nvie/gitflow — 2010 年前后的原始 shell 脚本， 十多年来无人维护。
• petervanderdoes/gitflow-avh — AVH 分支版本， 已不再积极开发。

如果 command -v git-flow 指向 mise 的 shim 目录之外， 或者 brew list 显示 git-flow / git-flow-avh， 请在安装 git-flow-next 之前执行下方的从旧版 git-flow / gitflow-avh 迁移流程。 二进制文件名称（git-flow）相同； 在 $PATH 中只能有一个生效。

硬性规则

1. 只允许使用 git-flow-next。 不得使用 nvie/gitflow、gitflow-avh 或任何 shell 脚本分支版本。

2. 必须通过 mise 的 aqua 后端安装，遵循 mise 技能的要求 — 在 mise.toml 中固定为 aqua:gittower/git-flow-next， 并记录在 mise.lock 中。 此处必须使用显式的 aqua: 前缀， 覆盖 mise 技能对裸名称的偏好： 裸名称 git-flow 在 mise 的注册表中存在歧义 （旧版 nvie/gitflow 和 gitflow-avh 也使用这个名称）， 因此，直接指定 aqua 软件包是确保使用 git-flow-next 的唯一方式。 不得使用 brew install git-flow-next、 不得手动下载二进制文件、 不得使用 go install。

3. 功能分支的上游合并策略必须是变基为单个提交。 分支会在完成之前合并为一个手写说明的提交（而非由合并工具完成）， 这样可以保留原始作者信息，也不会把每个 WIP 提交的说明拼接到 develop 上。 每个仓库只在一个地方执行一次：

   • 本地完成工作流 — 设置 gitflow.branch.feature.upstreamstrategy = rebase， 使 git flow feature finish 将功能分支线性变基到 develop， 不创建合并提交。 贡献者负责先将分支合并为单个提交 （运行 git rebase -i $(git merge-base HEAD develop)，对 第一个提交以外的每个提交使用 fixup，然后写一条干净的说明）， 再运行 git flow feature finish。 不要使用 upstreamstrategy = squash — 它会创建一个没有原始作者信息的新提交，并默认拼接所有提交说明， 而这正是本策略要避免的行为。
   • PR 审查工作流 — 不设置该键，并将托管平台的 PR 合并按钮配置为变基并合并 （不要选“压缩并合并”，也不要直接“创建合并提交”）。 贡献者在请求审查之前，先在本地将分支合并为单个提交 （如上所述进行交互式变基）， 这样合入 develop 的就是他们编写的一条干净提交。 托管平台的“压缩并合并”不可作为替代方案 — 默认情况下，它会将每个提交的说明拼接到提交正文中， 而且根据平台设置， 生成的提交可能会将合并者而非贡献者标为作者。 合并者必须在每个 PR 上手动覆盖这两项设置。

   每个仓库选择一种方式； 混用会导致重复应用或失败。 发布和热修复保留默认的 merge 策略， 以确保合并提交与版本标签保持对应。

4. 使用 classic 预设。 main 和 develop 是长期存在的分支； 主题前缀为 feature/、release/、hotfix/、bugfix/。 其他预设（github、gitlab）不在本技能范围内 — 如果项目明确要求使用其中一种， 请参阅 git-flow-next 上游文档， 不要应用本技能的其余内容。

根据文档核实记忆

git-flow-next 还很新，不同版本之间会更改标志名称、配置键和预设行为。 如果以下任何内容——命令标志、配置键、预设内容、二进制文件名称、版本可用性——看起来陌生或已过时，请在编写配置或运行命令前，前往 https://git-flow.sh/docs 核实。 不要猜测。

流程：通过 mise 安装

本技能说明要安装什么； mise 技能规定如何安装—— 创建包含必需 [settings] 区块的 mise.toml、 运行 mise trust / mise install / mise ls、 处理锁文件， 以及提交更改。 如果项目尚未使用 mise， 请先运行 mise 技能的设置流程； 不要在此重复其步骤。

git-flow-next 专属步骤：

1. 选择一个固定版本 （发布版本： https://github.com/gittower/git-flow-next/releases）。

2. 通过显式的 aqua: 后端， 在 mise.toml 的 [tools] 下添加条目—— pkgs/gittower/git-flow-next aqua 软件包会提供一个 git-flow 二进制文件， 硬性规则 2 解释了为什么此处不能安全地使用裸名称：

   [tools]
   "aqua:gittower/git-flow-next" = "1.1.0"
   

3. 按照 mise 技能运行安装后， 专门验证 git-flow-next：

   git flow version
   

它应显示固定版本。 如果显示其他版本， 说明另一个 git-flow 二进制文件正在 $PATH 中遮蔽 mise 管理的版本—— 使用 command -v git-flow 找到它并将其移除 （常见原因是通过 Homebrew 安装了旧版 git-flow 或 git-flow-avh）。

流程：初始化仓库

在仓库根目录运行。 classic 预设会配置 Gitflow 分支和前缀： main ← develop ← feature/， 以及 release/、hotfix/、bugfix/。 --defaults 会跳过交互式提示。

git flow init --preset=classic --defaults

如果生产分支不是 main， 或任何分支／前缀需要使用不同名称， 请去掉 --defaults 并传入文档中说明的覆盖项 （--main=master、--develop=…、--feature=feat/ 等）。

然后，在本地完成工作流（硬性规则 3）中， 启用功能分支完成时的变基：

git config gitflow.branch.feature.upstreamstrategy rebase

在 PR 审查工作流中， 跳过此命令，改为将平台的 PR 合并按钮配置为“变基并合并”。

验证：

git config --get-regexp '^gitflow\.'

输出应列出预设的分支和前缀条目。 对于本地完成工作流，输出还必须包含 gitflow.branch.feature.upstreamstrategy rebase； 对于 PR 审查工作流，该键必须缺失。

流程：功能分支生命周期

以下流程描述的是本地完成工作流 （硬性规则 3）： 贡献者先在本地将功能分支压缩为单个提交， 然后 git flow feature finish 会将该提交变基到 develop。 对于 PR 审核工作流， 请跳转到下方的替代流程。

开始：

git flow feature start <name>

这会从 develop 创建 feature/<name> 并检出该分支。 按常规在该分支上工作 — 提交；如有需要，可推送以备份或共享。

发布（可选，用于协作）：

git flow feature publish <name>

压缩为单个提交（硬性规则 3）： 在完成之前， 以当前 develop 为基准对功能分支进行交互式变基， 并将除第一个提交外的所有提交合并到第一个提交中， 然后将最终的提交消息改写为简洁、完整的摘要。

git rebase -i $(git merge-base HEAD develop)
# In the editor: keep the first line as `pick`,
# change every following line to `fixup` (drops their messages) or
# `squash` (keeps and lets you edit them).
# Save and exit; if you used `squash` or `reword`,
# the editor reopens for the final commit message —
# write a clean, self-contained summary.

如果现有提交消息都不值得保留，可使用以下等效快捷方式：

git reset --soft $(git merge-base HEAD develop)
git commit -m "<clean summary of the feature>"

压缩后， git log develop..HEAD 应恰好显示一个提交。

完成：

git flow feature finish <name>

设置 upstreamstrategy=rebase 后， 该命令会：

1. 切换到 develop，
2. 将（现在只有一个提交的）feature/<name> 线性地变基到 develop — 不会创建合并提交， 并保留原作者信息和手写的提交消息，
3. 删除本地 feature/<name> 分支。

之后推送 develop。不带参数的简写适用于当前分支：

git flow finish

如果跳过压缩步骤， git flow feature finish 仍会执行变基， 但功能分支上的每个 WIP 提交都会作为单独的提交进入 develop — 这不符合本技能要求的策略。 finish 还会删除功能分支， 因此要恢复，就需要对 develop 本身进行交互式变基 （git rebase -i origin/develop），将新提交压缩为一个提交， 并且必须在推送之前完成 — 只有这些提交仍在本地时，这样做才安全。 不要跳过压缩步骤。

PR 审核替代流程

在 PR 审核工作流中（硬性规则 3）， 变基合并由托管平台上的 “rebase and merge”按钮完成， 而不是通过 git flow feature finish。 贡献者仍须在创建或更新 PR 之前， 在本地将分支压缩为单个提交 （使用上述相同的 git rebase -i / git reset --soft 流程） — 否则多个提交会进入 develop， 从而违背该策略。 PR 合并后：

• 远程功能分支已被删除 （在常见设置下，平台会在合并时将其删除）；
• 使用 git branch -d feature/<name> （或 git flow feature delete <name>）删除本地副本；
• 不要运行 git flow feature finish — 这会重复应用更改或导致失败。

流程：发布分支

发布分支保留默认的合并策略， 以便将合并提交与标签配对。

git flow release start 1.4.0
# bump version files, update changelog, commit
git flow release finish 1.4.0 --tag --message "release 1.4.0"

release finish 会合并到 main， 为合并创建标签， 将 main 合并回 develop， 并删除发布分支。

流程：热修复分支

git flow hotfix start 1.4.1
# fix, commit
git flow hotfix finish 1.4.1 --tag --message "hotfix 1.4.1"

hotfix finish 与 release finish 类似： 合并到 main， 创建标签， 将 main 合并回 develop， 并删除热修复分支。

流程：缺陷修复分支

缺陷修复分支和功能分支一样，以 develop 为目标， 但仅用于非功能类缺陷； 生产环境修复应通过 hotfix 进行。 其生命周期与功能分支相同：

git flow bugfix start <name>
# fix, commit
git flow bugfix finish <name>

bugfix finish 使用默认的 merge 上游策略。 如果仓库希望像功能分支一样压缩缺陷修复分支 （硬性规则 3 中的本地完成工作流）， 请设置相应的键，并遵循相同的“先压缩后完成”流程 （交互式变基 → 单个提交 → 完成）：

git config gitflow.branch.bugfix.upstreamstrategy rebase

在 PR 审核工作流中， 将缺陷修复分支按功能分支处理 — 由平台执行变基合并， 不在本地运行 git flow bugfix finish。

迁移流程：从旧版 git-flow / gitflow-avh 迁移

当 command -v git-flow 指向 Homebrew 或手动安装的 nvie/gitflow 或 petervanderdoes/gitflow-avh，或者 brew list / apt list --installed 显示已安装 git-flow 或 gitflow-avh 时触发。

1. 确认现有设置使用的是旧版分支： command -v git-flow， 然后运行 git-flow version — 旧版 AVH 分支会输出 AVH Edition， nvie 的版本会输出类似 0.4.x 的版本号，且不带 Go/Tower 归属信息。

2. 读取旧版 Gitflow 配置 — 仅提取分支名称和前缀名称， 不要原样重新应用。 旧版分支和 git-flow-next 使用不同的键结构 （旧版：gitflow.branch.master、gitflow.prefix.feature； git-flow-next：gitflow.branch.<type>.parent、 gitflow.branch.<type>.prefix）， 因此不能直接重新应用捕获到的键 — 它们只能作为 git flow init 标志参数的取值来源：

   git config --get-regexp '^gitflow\.'
   

   记下 gitflow.branch.master、 gitflow.branch.develop、 gitflow.prefix.feature、 gitflow.prefix.release、 gitflow.prefix.hotfix 和 gitflow.prefix.bugfix 的值。

3. 删除旧版二进制文件：

   • Homebrew：brew uninstall git-flow 或 brew uninstall git-flow-avh。
   • 手动安装：从其 $PATH 所在位置删除二进制文件。

4. 按照上述流程安装 git-flow-next。

5. 重新运行 git flow init， 将第 2 步捕获的名称作为覆盖值传入 （若某个值已与 classic 预设默认值一致，则省略对应标志）：

   git flow init --preset=classic \
     --main=<captured master/main> \
     --develop=<captured develop> \
     --feature=<captured feature prefix> \
     --release=<captured release prefix> \
     --hotfix=<captured hotfix prefix> \
     --bugfix=<captured bugfix prefix>
   

   如果捕获到的所有值都与 classic 默认值一致， 只需运行 git flow init --preset=classic --defaults。

6. 按照工作流重新应用 rebase 设置（硬性规则 3）：

   • local-finish： 运行 git config gitflow.branch.feature.upstreamstrategy rebase， 并对每个功能分支执行先压缩再完成的流程 （交互式 rebase → 单个提交 → git flow feature finish）；
   • PR-review： 跳过此配置， 将平台的 PR 合并按钮设置为“rebase and merge”， 并在创建 PR 之前在本地将功能分支压缩为单个提交。

7. 验证 git flow version 显示 mise.toml 中指定的 git-flow-next 版本， 并确认 command -v git-flow 指向 ~/.local/share/mise/ （或 mise 放置 shim 的其他位置）。

报告

完成更改后， 说明新增或更新了 mise.toml 中的哪一项 （工具、后端、版本）， 设置了哪些 gitflow.* 键， 删除了哪些旧版二进制文件， 以及用户接下来应运行的命令 （git flow version、 git flow feature start <name>， 或适合当前任务的其他命令）。