11.1.使用 Git 制作补丁

当某个 port 不是作者提供的最新版本时， 应更新 /usr/ports 的本地工作副本。这个 port 可能已经被更新到了新的版本。

当需要处理几个以上的 port 时， 使用 Git 来保持整个 Ports 的最新版本可能会更容易， 就像手册中描述的那样。这样做还有一个好处， 就是可以跟踪所有 port 的依赖关系。

下一步是看看是否有一个已经在等待的更新。要做到这一点， 有两个选择。有一个可以搜索 FreeBSD 问题报告 (PR) 或 bug 数据库的界面。在 Product multiple select 菜单中选择 Ports & Packages， 并在 Summary 字段中输入 port 的名字。

如果没有悬而未决的 PR， 下一步就是给这个 port 的维护者发一封邮件， 如 make maintainer 所示。那个人可能已经在进行升级了， 或者有理由现在不升级这个 port (因为， 例如， 新版本的稳定性问题)， 因此没有必要重复他们的工作。请注意， 未维护的 port 会以 [e-mail] 的维护者列出， 这只是一般的 ports 邮件列表， 所以在这种情况下， 在那里发送邮件可能没有帮助。

如果维护者要求你进行升级， 或者没有维护者， 那么请通过准备升级来帮助 FreeBSD! 请使用基本系统中的 diff(1) 命令来完成这项工作。

要为单个补丁创建合适的 diff，请将需要打补丁的文件复制到 something.orig ， 将改动保存到 something ，然后创建补丁。

% diff -u something.orig something > something.diff

否则， 要么使用 git diff 的方法 (Using Git to Make Patches)， 要么将 port 的内容复制到一个完全不同的目录， 并使用新旧 port 目录的递归 diff(1) 输出的结果 (例如， 如果修改后的 port 目录叫做 superedit ，而原来的目录在我们的树中叫做 superedit.bak ，那么保存 diff -ruN superedit.bak superedit 的结果)。统一的或上下文的 diff 都可以， 但 port committers 通常更喜欢统一的 diff。请注意 -N 选项的使用 - 这是一种公认的方法， 可以强制 diff 正确处理新文件被添加或旧文件被删除的情况。在给我们发送差异之前，请检查输出，以确保所有的修改都是合理的。(特别是，请确保首先用 make clean 清理工作目录）。

注意

如果某些文件被添加、复制、移动或删除，请将这些信息添加到问题报告中，以便拾取补丁的提交人知道该执行哪些 git(1) 命令。

为了简化对补丁文件的普通操作，可以使用补丁中描述的 make makepatch。还有其他工具存在，比如 /usr/ports/Tools/scripts/patchtool.py 。在使用它之前， 请阅读 /usr/ports/Tools/scripts/README.patchtool 。

如果这个 port 没有被维护， 而你正在积极使用它， 请考虑自愿成为它的维护者。FreeBSD 有超过 4000 个 port 没有维护者， 这也是一个一直需要更多志愿者的领域。(关于维护者职责的详细描述， 请参考开发者手册中的章节。

要提交差异， 请使用 bug 提交表单 (产品 Ports & Packages, 组件 Individual Port(s))。始终包括带有 port 名称的类别， 后面是冒号， 以及问题的简短描述。例如： category/portname: add FOO option ； category/portname: Update to X.Y 。请在消息中提及任何添加或删除的文件，因为在做提交时必须向 git(1) 明确指定这些文件。 不要对差异进行压缩或编码。

在提交错误之前，请查看问题报告文章中的撰写问题报告部分。 它包含了更多关于如何编写有用的问题报告的信息。

重要

如果升级是出于安全考虑或当前提交的 port 中存在严重的错误， 请通知 Ports Management Team [e-mail] 以请求立即重建和重新发布该 port 的软件包。否则，毫无戒心的 pkg 用户将在几周内继续通过 pkg 安装来安装旧版本。

注意

请使用 diff(1) 或 git diff 来创建对现有 port 的更新。其他格式包括整个文件， 无法查看更改的内容。 如果不包括 diff， 可能会忽略整个更新。

现在所有这些都完成了，请阅读 Keeping Up 中关于如何保持最新的内容。

11.1.使用 Git 制作补丁

如果可能的话，请提交 git(1) 补丁或差异。它们比“新旧”目录之间的差异更容易处理。 如果 Ports 在开始工作后有什么修改， 或者 committer 要求修正什么， 则更容易看到哪些改动， 以及更新 diff。此外， 用 git-format-patch(1) 或 git-diff(1) 生成的补丁可以很容易地用 git-am(1) 或 git-apply(1) 来应用， 并会为 committer 节省一些时间。最后，由 git-format-patch(1) 生成的 git 补丁包括你的作者信息和提交信息。这些将被记录在版本库的日志中，这也是推荐的提交修改的方式。

% git clone https://git.FreeBSD.org/ports.git ~/my_wrkdir
% cd ~/my_wrkdir

① 当然，这可以是任何地方。构建 ports 并不限于 /usr/ports/ 内。

② git.FreeBSD.org 是 FreeBSD 的公共 Git 服务器。参见 FreeBSD Git 仓库 URL 表 以了解更多信息。在 port 目录中， 可以进行任何需要的修改。如果添加、移动或删除一个文件，请使用 git 来跟踪这些改动。

% git add new_file
% git mv old_name new_name
% git rm deleted_file

请确保使用 Testing the Port 和 Checking the Port with portlint 中的检查表来检查 port 。

同时， 用 make makesum 来更新 distinfo 中的校验和参考。

在打补丁之前，取来最新的版本库，并在其基础上重新建立修改。仔细观察并跟踪输出结果。如果有哪个文件没能重新归档，说明在你编辑同一个文件时，上游文件发生了变化，需要手动解决这些冲突。

% git fetch origin main
% git rebase origin/main

检查为该补丁所做的修改。

% git status
% git diff --staged

最后一步是对这些改动打一个统一的 diff 或补丁。

用 git-format-patch(1) 来生成一个补丁。

% git checkout -b my_branch
% git commit
% git format-patch main

这将生成一个名为 0001-foo.patch 的补丁。这是首选的方法，因为它包括了作者身份，而且当你在做一系列不打算压在一起的修改时，它也更容易。

或者，用 git-diff(1) 生成一个统一的差异。

% git diff --staged > ../`make -VPKGNAME`.diff

这将产生一个名为 foo-1.2.3.diff 的差异。其中 foo 被替换为提交信息的第一行，也就是提交信息的主题。

打完补丁后，可以切换到主分支，开始其他开发。

% git checkout main

一旦补丁被接受并合并，你可以根据需要删除本地开发分支。

% git branch -D my_branch

注意

如果有文件被添加、移动或删除，请使用带 add、mv 和 rm 参数的 git(1) 命令。 git mv 必须在应用补丁之前运行。git add 或 git rm 必须在应用补丁之后运行。

按照问题报告提交指南发送该补丁。