在git命令SYNOPSIS中`()`的含义是什么？

Question

在概要中git reset:

'git reset'( - patch | -p)[<tree-ish>] [ - ] [<paths> ...]

我对标记的含义有疑问.

我知道[]代表选项,<>代表替换.但是,这是什么意思()？如果没有|,是否还需要括号？

我没有在POSIX 实用程序约定中找到相关线索.

Answer 1

git的CodingGuidelines中包含了这一点,可以在他们的Github上找到.它为贡献者提供了样式指南,同时还描述了如何编写帮助选项.其他来源如POSIX或BSD不应被视为权威,特别是因为它们并不总是符合POSIX ¹.以下摘录位于文件底部附近:

Placeholders are spelled in lowercase and enclosed in angle brackets:
   <file>
   --sort=<key>
   --abbrev[=<n>]

Optional parts are enclosed in square brackets:
   [<extra>]
   (Zero or one <extra>.)

   --exec-path[=<path>]
   (Option with an optional argument.  Note that the "=" is inside the
   brackets.)

   [<patch>...]
   (Zero or more of <patch>.  Note that the dots are inside, not
   outside the brackets.)

Multiple alternatives are indicated with vertical bars:
   [-q | --quiet]
   [--utf8 | --no-utf8]

Parentheses are used for grouping:
   [(<rev> | <range>)...]
   (Any number of either <rev> or <range>.  Parens are needed to make
   it clear that "..." pertains to both <rev> and <range>.)

   [(-p <parent>)...]
   (Any number of option -p, each with one <parent> argument.)

   git remote set-head <name> (-a | -d | <branch>)
   (One and only one of "-a", "-d" or "<branch>" _must_ (no square
   brackets) be provided.)

And a somewhat more contrived example:
   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
   Here "=" is outside the brackets, because "--diff-filter=" is a
   valid usage.  "*" has its own pair of brackets, because it can
   (optionally) be specified only when one or more of the letters is
   also provided.

¹:以下摘录位于文件顶部:

与其他项目一样,我们也有一些指导方针可以保留代码.对于一般的Git,一些粗略的规则是:

• 最重要的是,我们从不说"它在POSIX中;如果您的系统不符合它,我们将很乐意忽略您的需求." 我们生活在现实世界中.

• 但是,我们经常说"让我们远离那个结构,它甚至不在POSIX中".

• 尽管有上述两条规则,我们有时会说"虽然这不是在POSIX中,但它(如此方便|使代码更具可读性|具有其他良好的特性),实际上我们关心的所有平台都支持它,所以让我们用它".

  同样,我们生活在现实世界中,它有时是一种
  判断力,这种决定更多地基于人们所面临的现实世界限制而不是纸质标准所说的.