Git 文档中的错误？

Question

根据this SO question，Git 手册页是从 Git 文档自动转换的（不使用 mdoc 或 groff），因此某些用法语法和手册页不符合 POSIX Utility Argument Syntax。

例如：

man git-config

列表

git config [<file-option>] [type] --add name value

在“Synopsis”下（根据 POSIX 语法，这应该在名为“Usage”的标题下，Git 手册页中“Description”标题下的内容应该在名为“Synopsis”的标题下）和name并且value 应该出现在<>s 中以表明它们是占位符。

更令人困惑，

man git-rebase

列表

git rebase [-i | --interactive] [<options>] [--exec <cmd>]
               [--onto <newbase> | --keep-base] [<upstream> [<branch>]]
       git rebase [-i | --interactive] [<options>] [--exec <cmd>] [--onto <newbase>]
               --root [<branch>]
       git rebase (--continue | --skip | --abort | --quit | --edit-todo | --show-current-patch)

根据 POSIX 语法，git rebase 可以在没有任何选项或参数的情况下成功运行，但事实并非如此。

由于 Git 文档不包含任何有关如何阅读命令行用法语法的部分，我如何理解 git rebase 的用法语法？是否应该将<branch> 放在[] 之外以正确表明它实际上是命令的非可选参数？

Answer 1

Git 努力在其手册页中使用准确的语法描述，尽管可能有人犯了错误。 [] 语法表示可选参数，括号表示需要其中一个选项的用法。这可能是也可能不是 POSIX 的做法，但通常每个 Unix 系统对于如何格式化手册页的标准略有不同，因此应该会出现一些差异。如果你对改变有强烈的感觉，你可以在 Git 列表上提出这样的改变，然后发送一些补丁。

正如 jthill 所指出的，可以在没有选项或参数的情况下使用 git rebase。在您的上下文中，它可能有用，也可能没有用。就个人而言，我更喜欢在使用 Git 进行 rebase 时更加明确，所以我不使用那种语法，但这是个人偏好；即使我选择不这样做，该命令也可以这样使用。