AGit 工作流用法

Forgejo 提供对 AGit-Flow 的有限支持。

与 Gerrit 工作流类似，你可以仅使用 git push 向 Forgejo 实例上的仓库提交修改，无需先创建 fork 或功能分支，再到网页中创建拉取请求。

通过推送选项 -o 和 Refspec（Git 使用的位置标识符），可以提供创建拉取请求所需的信息，例如目标分支与标题。

创建拉取请求

为便于理解，本文先给出示例。

之后会列出全部参数，并说明如何在 rebase 或 amend 提交后避免创建重复拉取请求。

用法示例

假设你克隆了仓库，并在 main 分支上创建新提交。使用当前检出的分支，创建以 main 为目标的拉取请求：

git push origin HEAD:refs/for/main -o topic="agit-typo-fixes"

HEAD:refs/for/main 是 Refspec。HEAD 指当前检出的引用，也可换为其他本地引用，例如分支。refs/for/main 是目标远程引用，其中 main 为希望合入修改的目标分支。

topic 会显示在拉取请求中，并用于把后续提交关联到同一拉取请求。

使用 topic 参数设置主题

主题也可放在 Refspec 的 <topic> 位置。下例与上例等价：从当前 HEAD 创建拉取请求，目标为 main，主题为 agit-typo-fixes。

# `agit-typo-fixes` is the topic parameter
git push origin HEAD:refs/for/main/agit-typo-fixes

推送尚未检出的引用（非 HEAD）

假设要向远程 new-feature 分支提交拉取请求，主题为 implement-part12，但修改位于尚未检出的本地 my-new-feature 分支。无需切换分支，直接指定该本地分支名即可：

git push origin my-new-feature:refs/for/new-feature/implement-part12

设置标题与描述

还可以使用 title、description 等推送选项。以下示例仍以 main 为目标：

git push origin HEAD:refs/for/main -o topic="implement-part12" \
  -o title="Title of the PR" \
  -o description="This can be **any** markdown content."

这两个选项都是可选的。省略时，使用第一个提交的标题与描述。

description 推送选项不支持换行。多行描述可以编码为 base64 来处理，参阅 forgejo/forgejo#8479。

改变默认推送方式

要省略每次推送的 Refspec，可将 Git 的默认推送方式设为 upstream：

# To only set this option for this specific repository
git config push.default upstream

接着执行：

git config branch.my-new-feature.merge refs/for/main/implement-part12

之后只需运行 git push，便可向拉取请求推送提交，无需指定 Refspec。pull、fetch、rebase 等操作也会默认针对该 AGit 拉取请求。

参数

git push <remote-nam e> <local-re f>:refs/<for|draft|for-review>/<branch>/<topic> [-o <topic|title|description|force-push>]

可用参数如下：

– <remote-name>：远程仓库名称，例如 origin，必填。

– <local-ref>：要推送的本地引用，例如 HEAD、my-branch 或提交哈希，必填。

– refs/<for|draft|for-review>/<branch>/<topic>：Refspec，必填。

– for、draft、for-review：拉取请求类型。for 创建普通拉取请求；draft 与 for-review 目前会被静默忽略。

– <branch>：希望合入的目标分支，必填。

– <topic>：远程拉取请求主题。留空时，必须通过 -o topic 提供。

– -o <topic|title|description|force-push>：推送选项。

– topic：本质上是一个标识符。留空时使用 Refspec 的 topic；两处都没有时 Forgejo 报错。

– title：拉取请求标题。留空时使用第一个新 Git 提交的首行。

– description：拉取请求描述。留空时使用第一个新 Git 提交的描述。

– force-push：对已有提交执行 rebase、amend 或追溯修改时需要。否则即使 topic 相同，也会创建新拉取请求。使用时设为 true。

向 AGit 创建的拉取请求追加提交时，必须使用相同 topic。Forgejo 依赖 topic 和线性提交历史，将新提交关联到现有开放拉取请求。覆盖现有拉取请求内容时，使用 force-push 参数。

**注意**

如果该 topic 对应的拉取请求已经合并或关闭，不论 force-push 值为何，都会创建新的拉取请求。

对于 Gerrit 用户：Forgejo 不支持 Gerrit 的 Change-Id。

评审工作流

可像评审其他拉取请求一样，在网页中评审 AGit 拉取请求。

要查看命令行操作说明，点击拉取请求表单底部的 View command line instructions 下拉菜单。

—

原文：AGit Workflow Usage，Forgejo 文档贡献者。本文为中文翻译。该页单独声明采用 Apache-2.0 许可，优先于网站通用许可；其来源链接与许可声明保留在原页末尾。

原始衍生来源：Gitea AGit 文档。许可副本随交接包保存为 APACHE-2.0.txt。