В чем смысл `()` в команде git СИНТАКСИС?

Question

В synopsis из git reset:

'сброса мерзавец' (--patch | -р) [< дерево-иш >] [-] [< пути > ...]

У меня проблема с значением маркеров.

Я знаю [] означает варианты, <> обозначает замену. Но, в чем смысл ()? Если нет |, нужны ли скобки?

Я не нашел родственников в POSIX Utility Conventions.

Answer 1

Это покрыто git's 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, это (так удобно | делает код гораздо более читаемых | имеют другие хорошие характеристики) и практически все платформы мы заботиться о поддержке, поэтому давайте использовать его ».

  Опять же, мы живем в реальном мире, и это иногда
  суждения вызов, решение, основанное больше на реальных ограничениях людей сталкиваются, чем то, что говорит стандартная бумага.

Answer 2

С РУЧНОЙ СТР (5), форматами файлов BSD Manual, раздел «MANUAL Синтаксисом»:

В некоторых случаях вы можете даже увидеть целые группы аргументов, обернутой скобку и разделенных вертикальным сепаратор , Это один из способов показать, что команда имеет более одного действительного синтаксиса. На других страницах руководства это выражается в виде нескольких строк в синопсисе, каждый из которых начинается с имени команды. Разделенный формат является более распространенным (и более читаемым), но не всегда возможен для команд с особенно сложным синтаксисом. Наконец, наиболее важным обозначением является использование многоточия (...). Это указывает на то, что в этот момент могут быть добавлены дополнительные аргументы.