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

Question

在git reset的synopsis中：

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

我对标记的含义有疑问。

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

我在POSIXUtility Conventions中没有找到相关线索。

Answer 1

来自手册页 (5)，BSD 文件格式手册，第 "MANUAL PAGE SYNTAX" 节：

In some cases, you may even see entire groups of arguments wrapped with brackets and separated by a vertical separator. This is one way of showing that a command has more than one valid syntax. In other manual pages, this is expressed by having multiple lines in the synopsis, each of which begins with the command name. The separated format is more common (and more readable), but is not always possible for commands with particularly complex syntax. Finally, the most important notational convention is the use of the ellipsis (...). This indicates that additional arguments may be added at this point.

Answer 2

这包含在 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.

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

What's the meaning of `()` in git command SYNOPSIS?

git

syntax

posix