在 Forgejo 中使用拉取请求与 Git 协作流程

以拉取请求协作的好处

注意仓库和组织的权限设置；不要轻信陌生来源的改动。使用拉取请求可以更方便地审查和管理贡献，而合并权限只交给项目维护者或所有者。

虽然个人或团队完全可以把 Git 项目作为共享的中央仓库使用，采用拉取请求的协作方式仍有不少好处：

• 主项目仓库只需少量拥有完整权限的维护者批准拉取请求，贡献者可以在自己的分叉仓库中工作。
• 每个拉取请求集中保存修复或功能分支的完整编辑历史，贡献者可以按需要压缩提交，或保留提交记录。

创建拉取请求

假设要向示例项目 knut/examples 贡献代码。首先，在项目页右上角点击 Fork，创建自己的分叉。

然后将分叉克隆到本机。本例假设已经配置 SSH 密钥，通常只需配置一次：

git clone git@codeberg.org:<YOURCODEBERGUSERNAM E>/examples.git

原页面占位符 <YOURCODEBERGUSERNAM E> 含有一个空格。实际执行前应将整个占位符替换为自己的用户名，并移除尖括号与占位空格；不要直接运行这一行示意命令。

创建功能分支，然后进行修改、提交、推送，再继续修改、提交、推送：

git checkout -b feature
# make some changes
git commit -m "first feature"
git push    # here you get asked to set your upstream URL, just confirm
# do more work, edit...
git add new_file.png
git commit -m "second feature introducing a new file"
git push
# ...
git commit -m "more work, tidy-up"
git push

这段示意流程没有展示每一次暂存操作；提交前应将本次改动加入暂存区。首次推送时，Git 可能要求显式设置分支的上游，并不会在所有环境中弹出可确认的 URL 提示。需按实际远程与分支配置处理。

接着访问主仓库页面，点击 New Pull Request 创建拉取请求。满足以下条件时，系统会自动显示对应按钮：

• 你推送的分支仍然存在，并且不是默认分支。
• 推送发生在最近 6 小时内。
• 该分支没有已经打开的拉取请求。

审查改动

在拉取请求页面的 Files Changed 标签中，点击 Review，可以批准拉取请求或要求修改。

每个变更行旁的加号允许为该行添加评论，例如提出修改建议。若要评论连续多行，按住 Shift，点击范围第一行旁的加号，向下拖到最后一行再松开；高亮范围会附在同一条评论中。

拉取请求包含多个提交时，可以使用 Review 按钮左侧的选择按钮，只审查某个提交。

请求审查和代码所有者

拉取请求右侧栏有 Reviewers 区域。点击标题可打开下拉列表，向一个或多个仓库协作者请求审查。

也可以在仓库根目录、docs 目录或 .forgejo 目录添加 CODEOWNERS 文件，自动发出审查请求。

每一行是一条规则：先写用于匹配变更文件路径的 Go 格式正则表达式，再写一个或多个用户名或组织团队名，各项用空白分隔。正则表达式前可以加感叹号 !，形成否定规则。

用户以用户名标识；团队以“组织名/团队名”标识，两者都可以选择加 @ 前缀。

提交拉取请求后，系统会用 CODEOWNERS 规则检查变更。如果任一变更路径匹配一条普通规则，就自动向该规则指定的所有用户或团队请求审查。否定规则相反：当任一变更路径不匹配规则的正则表达式时，发出审查请求。

文件可以包含空行，以及以 # 开头的注释。例如：

# Request review from User001 whenever anything in `src` changes
src/.* @User001

# Request review from the editors team in MyOrg whenever anything
# in `docs` changes
docs/.* @MyOrg/editors

# Request review from User002 whenever anything but `README.md` changes
!README\.md User002

这里使用 Go 正则表达式，不能把规则直接按其他托管平台的 glob 语法解释。

通过变基跟上上游项目

在开发功能分支期间，上游仓库可能继续变化，需要让分支基于新的上游版本，并解决相关合并冲突。

要跟踪上游，先添加一个指向原项目的第二远程；通常只需执行一次：

git remote add upstream git@codeberg.org:knut/examples.git

原文示例使用 SSH 地址。如果希望通过 SSH 拉取而不反复输入凭据，需先正确配置 SSH 认证。

然后从上游拉取，并基于其最新分支，例如 main，为本地分支变基：

git pull --rebase upstream main
git pull

第一条命令从 upstream main 拉取并变基；第二条未指定远程的 git pull 使用当前分支自己的跟踪配置。该额外操作是否需要，取决于项目配置，并不是所有仓库都应原样连续执行。变基前应确认工作区状态，以及分支是否与他人共享。

完成后，可以按通常流程推送改动，并点击 New Pull Request 创建拉取请求。

所有者权限与强制推送

项目所有者可以执行所有操作，包括通过强制推送修改或重写历史。某些情况下这很有用，例如撤销误提交或整理拉取请求，但对于默认分支等被其他人依赖的分支，透明且完整的历史通常更合适。