我在哪里可以报告 git 错误

Question

我正在尝试为 git 使用 mailmap.file 配置选项。然而，路径不是 shell 扩展的，这意味着我不能写 $HOME/.mailmap 或 ~/.mailmap。如果您将点文件与 homesick 之类的文件同步，并且在 Windows、OS X 和 Linux 上使用相同的 .gitconfig，这会很烦人。

我找不到任何 git 的 bugtracker，我不想用类似的东西向 git 邮件列表发送垃圾邮件。我应该如何报告这个错误/小烦恼？

Answer 1

使用git bugreport 使用标准模板撰写电子邮件正文。

将生成的文本文件复制并粘贴到电子邮件正文中，并将其发送到 git@vger.kernel.org。确保以纯文本形式发送它——HTML 将被退回。 （如果使用 GMail，请参阅 https://www.dummies.com/software/other-software/10-useful-gmail-settings/）。

Answer 2

如code google git-core 中所述（以及在 cmets 中的 Charles Bailey，它指向 git-scm community page）：

可以使用电子邮件地址 git@vger.kernel.org 将 Git 社区的问题或 cmets 发送到邮件列表。错误报告应发送至此邮件列表。

(mailing list archive here)

2020 年第二季度更新，您现在有了一个实际的 git bugreport 命令（见下文末尾）

2015 年更新：最新的参考仍然是 Git community page，正如 smoothgrips 指出的 in the comments 所提到的：

您无需订阅：您将在回复中被抄送。
回复时请保持抄送列表完整（使用“全部回复”）。
灰名单可能会使您的第一篇帖子延迟几个小时。

请注意，邮件服务器将拒绝带有“永久失败”消息的 HTML 邮件，因此请使用纯文本。

社区页面还指出“How to Report Bugs Effectively”...

如果你想贡献补丁，现在就去rtyley/submitgit，它可以帮助你关注patch submission process：

如果您在 github.com/git/git/ 上创建拉取请求，submitGit 可以将其发送到您的邮件列表，并正确格式化补丁。
讨论停留在原处——在列表中——但至少第一步要容易一些。

2015 年更新：Git For Windows now lives on GitHub (github.com/git-for-windows)，并生成非常最近版本：2.4.2+。
Msysgit is phased out，使用msys2 64-bits , 并导致 git-for-windows.github.io 而不是旧的现在已过时的 msysgit.github.io。

GitHub 镜像仓库镜像 git/git 在那里，但不幸的是，它不能用于问题或拉取请求。

---

2019 年更新：submitGit 有一个替代方案：GitGitGadget (gitgitgadget.github.io)，在 Git 2.22（2019 年第二季度）中提到

参见 Jeff King (peff) 的 commit c3a7dd7（2019 年 3 月 12 日）。
^{（由 Junio C Hamano -- gitster -- 合并到 commit 2d33728，2019 年 4 月 9 日）}

将拉取请求者指向 GitGitGadget

在在 GitHub 上打开拉取请求的人看到的贡献指南和 PR 模板中，我们提到了 submitGit 工具，它提供了一种查找邮件列表的替代方法。
这些天我们也有类似的 GitGitGadget 工具，我们应该明确表示这也是一种选择。

我们可以继续提及两种工具，但最好选择其中一种，以免用户选择过多。
毕竟，这里的目的之一是减少第一次或 不经常的贡献者。

还有几个理由更喜欢GGG：

1. submitGit 似乎还有一些粗糙的边缘。例如，它不会使用时间戳来帮助线程式邮件阅读器乱序处理 送货。
2. 主观上，GGG 现在似乎更常用在列表中，尤其是列表常客。
3. GGG 似乎正在更积极地发展（可能与第 2 点有关）。

所以让我们把 submitGit 换成 GGG。
当我们在那里时，让我们在 PR 模板中添加另一个指向 GGG 页面的链接，因为这是第一次学习它的用户想要去的地方。 阅读更多。

---

在 Git 2.25（2020 年第一季度）中，有一个关于对象枚举的教程，它提供了一个关于如何贡献/测试/报告错误的好例子。

参见Emily Shaffer (nasamuffin) 的commit e0479fa（2019 年 10 月 11 日）。
^{（由 Junio C Hamano -- gitster -- 合并于 commit 15d9f3d，2019 年 11 月 10 日）}

documentation: 添加物体行走教程

^{签字人：Emily Shaffer
帮助人：Eric Sunshine}

object walks 的现有文档似乎主要是为那些已经熟悉该过程的人提供参考。
本教程试图为几个基本的对象遍历提供入门级指南，以便新的 Git 贡献者可以学习这些概念，而不必费力地通过选项解析或特殊的大小写。

目标受众是刚开始接触对象行走概念的 Git 贡献者。
目标是让此贡献者准备好能够更轻松地理解和修改执行修订遍历的现有命令，尽管它也将使贡献者准备好创建执行遍历的新命令。

本教程涵盖了对象遍历期间涉及的结构的基本概述、设置基本提交遍历、设置基本全对象遍历以及为两种遍历类型添加一些配置更改。
它故意不包括如何创建新命令或从命令行或 gitconfigs 搜索选项。

https://github.com/nasamuffin/git/tree/revwalk 有一个相关的补丁集，其中包含本教程生成的代码的参考实现。

注意：该教程已在 Git 2.27（2020 年第二季度）中进行了修改：

参见Johannes Schindelin (dscho) 的commit e3f53ce（2020 年 3 月 28 日）。
^{（由 Junio C Hamano -- gitster -- 合并到 commit 7780604，2020 年 4 月 22 日）}

MyFirstObjectWalk：去掉不必要的条件语句

^{签字人：Johannes Schindelin
审核人：Emily Shaffer}

在给定的示例中，commit 不能是 NULL（因为这是循环条件：如果是 NULL，则根本不会输入循环体）。这位开发人员花了一两分钟时间才发现这是死代码。

让我们删除它，以免让未来的读者感到困惑。

---

在 Git 2.25（2020 年第一季度）中，GitGitGadget 已记录在案。

参见Emily Shaffer (nasamuffin) 的commit 3c8d754、commit 3ada78d、commit 4ed5562（2019 年 10 月 31 日）。
^{（由 Junio C Hamano -- gitster -- 合并到 commit f089ddd，2019 年 12 月 1 日）}

myfirstcontrib: 提示找到 gitgitgadget 允许器

^{签字人：Emily Shaffer}

GitGitGadget 是一个方便的工具，可以将针对 Git 的拉取请求转换为 Git-mailing-list-friendly-patch-emails，作为反垃圾邮件，要求所有新用户都是“/allow”ed由现有用户执行一次，然后它将为该新用户执行任何操作。

虽然本教程解释了该机制，但它并没有提供太多关于如何寻找允许新拉取请求的人的提示。
因此，请教我们的新 GitGitGadget 用户在哪里寻找可以将其姓名添加到列表中的人。

此补丁中的建议基于为 GitGitGadget 提出的建议：gitgitgadget/gitgitgadget PR 138

---

在 Git 2.25（2020 年第一季度）中，邮件列表归档和 nntp 服务的文档更新。

参见Jeff King (peff)commit 3eae30e、commit 46c6749（2019 年 11 月 27 日）。
^{（由 Junio C Hamano -- gitster -- 合并于 commit 3b3d9ea，2019 年 12 月 6 日）}

doc：用 lore.kernel.org 替换公共收件箱链接

^{签字人：杰夫·金}

既然我们现在推荐 lore.kernel.org（并且因为 public-inbox.org 域最终可能会消失），让我们也更新我们的内部引用以使用它。
这为我们的参考提供了面向未来的证明，并树立了我们希望人们效仿的榜样。

见“This list is now also archived on lore.kernel.org/git”

doc：用 lore.kernel.org 替换 MARC 链接

^{签字人：Denton Liu}

由于我们现在推荐 lore.kernel.org，请将 marc.info 链接替换为 lore.kernel.org。

虽然 MARC 已经存在了很长时间，但没有什么是永恒的（参见 Gmane）。
由于 MARC 使用不透明的消息标识符，切换到 lore.kernel.org 应该是一个严格的改进，因为即使 lore.kernel.org 出现故障，Message-ID 也将允许未来的读者在任何其他存档中查找引用的消息。

我们在 README.md 中留下了一个对 MARC 的引用，因为它是一个非常适合个人阅读的邮件存档，只是不适合将来链接邮件。

还有：

RelNotes: 用真实的 Message-ID 替换 Gmane

^{签字人：Denton Liu}

对 Gmane 的唯一引用在 RelNotes 中。
虽然这些肯定没有被积极使用，但它们可能对未来的读者具有历史意义，因此让我们确保邮件引用更加可靠。

将 Gmane 的链接替换为 lore.kernel.org 的链接（这是我们新的首选邮件列表存档，并且在 URL 中包含 Message-ID）和带有 Message-ID 的裸 Gmane ID 引用。

通过在 https://public-inbox.org/git/ 上搜索“gmane:<id>”并获取结果消息，找到了消息 ID。

关于lkml.org：

doc：将 LKML 链接替换为 lore.kernel.org

^{签字人：Denton Liu}

由于我们现在推荐 lore.kernel.org，请将 LKML 链接替换为 lore.kernel.org。

尽管 LKML 已经存在了很长时间，但没有什么是永恒的（请参阅 Gmane）。
由于 LKML 使用不透明的消息标识符，切换到 lore.kernel.org 应该是一个严格的改进，因为即使 lore.kernel.org 出现故障，消息 ID 也将允许未来的读者在任何其他存档中查找引用的消息。

---

在 Git 2.26（2020 年第一季度）中，为新贡献者提供了更多文档。

参见commit a2dc434（2020 年 2 月 14 日）和 commit 4bb4fd4（2020 年 1 月 24 日）Emily Shaffer (nasamuffin)。
^{（由 Junio C Hamano -- gitster -- 合并于 commit 325eb66，2020 年 2 月 25 日）支持>}

MyFirstContribution: 添加获取帮助的途径

^{签字人：Emily Shaffer}

有了https://lore.kernel.org/git/20191114194708.GD60198@google.com/，我们现在有了一个指导邮件列表，我们应该将有问题的新贡献者引导到该列表。

提及#git-devel，这是针对 Git 贡献者的；寻求帮助以共同获得第一个贡献是该频道的主题。如果人们不熟悉 IRC，还请提及一些约定。

因为导师名单和#git-devel都是Git贡献者的一个子集，最后列出main Git list并提一些发帖约定。

还有：

MyFirstContribution: 改写联系方式

^{签字人：Emily Shaffer
审核人：Jonathan Nieder}

尽量不要阻止新用户向 git@vger.kernel.org 发送问题，并解释指导列表与主列表对比的目的。

---

对于 Git 2.27（2020 年第二季度），在报告错误之前，请阅读（新）常见问题解答。

参见brian m. carlson (bk2204) 的commit 2149b67（2020 年 3 月 30 日）。
^{（由 Junio C Hamano -- gitster -- 合并到 commit 06aaafb，2020 年 4 月 22 日）}

docs：添加常见问题解答

^{签字人：brian m.卡尔森}

Git 是一款非常灵活且功能强大的软件。

但是，对于许多用户来说，它可能会令人生畏，并且有一组用户经常问的常见问题。

虽然我们已经有了一些新的用户文档，但值得添加一个常见问题解答来解决用户经常遇到的常见问题。

尽管其中一些在文档的其他地方有所提及，但经验表明用户很难找到，因此集中位置很有帮助。

添加此类常见问题解答并填写一些常见问题和答案。虽然现在的条目很少，但我们可以在未来扩展它以涵盖更多内容，因为我们会发现用户提出的新问题。

常见问题解答还解决了常见的配置问题，这些问题不仅适用于作为独立软件的 Git，还适用于人们使用的 CI 工具和托管服务提供商的生态系统，因为这些是常见问题的来源。

---

借助 Git 2.27（2020 年第二季度），您可以使用“bugreport”工具。

请参阅commit 8f0e984（2020 年 4 月 27 日）和commit 69bcbbc、commit 1411914、commit 617d571、commit 238b439、commit 709df95（2020 年 4 月 16 日）Emily Shaffer (nasamuffin)。
^{(由Junio C Hamano -- gitster -- 合并于commit dd094c2，2020 年 5 月 1 日）}

bugreport: 添加生成调试信息的工具

^{签字人：Emily Shaffer}

教 Git 如何提示用户提供良好的错误报告：重现步骤、预期行为和实际行为。之后，Git 可以学习如何从存储库中收集一些诊断信息。

如果用户可以向我们发送一份写得很好的错误报告，其中包含我们需要向用户索取的诊断信息，我们可以减少报告者和 Git 贡献者之间的问答往返次数。

如果用户将他们的存储库置于他们感到困惑的状态，他们也可能希望将这样的报告发送给他们当地的“Git 专家”。

git bugreport documentation 包括：

git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]

说明

将有关用户机器、Git 客户端和存储库状态的信息以及请求有关用户观察到的行为的信息的表单捕获到单个文本文件中，然后用户可以共享该文本文件，例如 Git 邮件列表，以便报告观察到的错误。

要求用户提供以下信息：

• 复制步骤
• 预期行为
• 实际行为

---

使用 Git 2.27（2020 年第二季度），“git bugreport”学会了报告存储库中启用的挂钩。

参见Emily Shaffer (nasamuffin) 的commit 788a776（2020 年 5 月 8 日）。
^{（由 Junio C Hamano -- gitster -- 合并到 commit 3583730，2020 年 5 月 14 日）}

bugreport: 收集填充钩子列表

^{签字人：Emily Shaffer}

有时，用户看到的故障可能与正在运行的特定挂钩有关，而用户可能没有意识到。
虽然挂钩的内容可能很敏感 - 包含用户数据或特定于用户组织的流程信息 - 只需知道挂钩正在某个阶段运行就可以帮助我们了解是否出现问题。

如果代码中没有明确的钩子名称列表，我们会根据文档编译自己的列表。这很可能会导致比特腐烂，但是对于错误报告工具的这个小改动来说，为可接受的钩子设计一个单一的事实来源是太多的开销。

---

使用 Git 2.28（2020 年第三季度），“git bugreport”学会报告正在使用的 shell。

参见Emily Shaffer (nasamuffin)commit 4a4804e、commit 39f4919（2020 年 5 月 12 日）。
^{（由 Junio C Hamano -- gitster -- 合并于 commit ce095ec，2020 年 6 月 9 日）}

help：将 shell 路径添加到 --build-options

^{签字人：Emily Shaffer}

如果基于 shell 的 Git 命令失败，了解构建 Git 并尝试指向哪个 shell 可能很有用。
$SHELL_PATH 在构建期间设置并用于启动联机帮助页查看器，以及git-compat-util.h，它在测试期间使用。
鼓励在错误报告中使用“git version --build-options”，因此在此处包含此信息是有意义的。

还有：

bugreport: 包含用户交互 shell

^{签字人：Emily Shaffer}

用户可能会抱怨 Git 与其交互式 shell 交互的方式，例如自动完成或 shell 提示。在这种情况下，了解他们以交互方式使用的 shell 对我们很有用。

---

Git 2.30（2021 年第一季度）已经描述了原始贡献者在回复评论评论后使用补丁更新中的解释的期望。

参见Junio C Hamano (gitster) 的commit a6d8d11（2020 年 11 月 20 日）。
^{（由 Junio C Hamano -- gitster -- 合并于 commit b94b1f9，2020 年 11 月 30 日）}

MyFirstContribition：回答问题不是故事的结局

^{审核人：Emily Shaffer}

评论交流可以从评论者开始询问“你在日志消息（或文档中）中的这个短语是什么意思？”，作者回答了它的意思，然后评论者说“啊，那个就是你的意思——那么逻辑的流程是有道理的”。

但这并不是故事的美好结局。
新的贡献者经常忘记，在上述交流中审查过的材料对于下一个阅读它的人仍然不清楚，直到它得到更新。

当我们在附近时，将审稿人用来指代 cmets 的动词“request”改写为“suggest”——这与同一段落后面出现的“original”和“suggested”之间的对比相匹配，更重要的是更清楚地表明，作者并不是要取悦审稿人的意愿，而是审稿人只是在帮助作者完善他们的提交。 提出了修改建议，感觉原版更好，还是那个评论

MyFirstContribution 现在包含在其man page 中：

审阅者可能会询问您在补丁集中写的内容，无论是 建议的提交日志消息或更改本身。你 应在您的回复信息中回答这些问题，但通常 审稿人问这些问题以理解您的意思的原因 写是因为你的补丁集需要澄清才能被理解。

不要仅仅满足于在您的回复中回答他们的问题 听他们说他们现在明白你想说什么了。 更新您的补丁以澄清审阅者遇到的问题， 并准备您的 v2；你用来解释你的 v1 来回答的话 审稿人的问题可能是有用的东西。你的目标是使 您的 v2 足够清晰，因此您无需提供 给下一个阅读它的人同样的解释。

---

在 Git 2.30（2021 年第一季度）中，已删除对不可重入 localtime() 的使用。

参见Taylor Blau (ttaylorr)commit 4f6460d（2020 年 11 月 30 日）。
^{（由 Junio C Hamano -- gitster -- 合并于 commit bb48056，2020 年 12 月 8 日）}

builtin/bugreport.c：使用线程安全的localtime_r()

^{签字人：Taylor Blau}

要生成其文件名，'git bugreport'^(man) 内置命令会使用 'localtime()' 向系统询问当前时间。
由于它使用共享缓冲区，因此它不是线程安全的。

虽然 'git bugreport'^(man) 不是多线程的，但使用localtime() 会触发一些静态分析工具的报错，并且快速

$ git grep -oh 'localtime\(_.\)\?' -- **/*.c | sort | uniq -c  

表明线程不安全的“本地时间”的唯一用法是在一个文档中。

因此，将此实例转换为使用线程安全版本以保持一致性，并安抚一些分析工具。

Answer 3

报告错误的最佳地点通常是邮件列表。您甚至不需要订阅帖子，只需发送电子邮件至：git@vger.kernel.org。

您可以找到有关邮件列表here的更多官方信息。

也检查一下：

• Documentation/CodingGuidelines
• Documentation/SubmittingPatches
• A note from the maintainer