git - git 命令概要中的 `()` 是什么意思？

Question

在synopsis的 git reset :

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

我对标记的含义有疑问。

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

我没有在 POSIX 中找到相关线索 Utility Conventions .

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.

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

Like other projects, we also have some guidelines to keep to the code. For Git in general, a few rough rules are:

• Most importantly, we never say "It's in POSIX; we'll happily ignore your needs should your system not conform to it." We live in the real world.

• However, we often say "Let's stay away from that construct, it's not even in POSIX".

• In spite of the above two rules, we sometimes say "Although this is not in POSIX, it (is so convenient | makes the code much more readable | has other good characteristics) and practically all the platforms we care about support it, so let's use it".

  Again, we live in the real world, and it is sometimes a
  judgement call, the decision based more on real world constraints people face than what the paper standard says.