Welcome to OGeek Q&A Community for programmer and developer-Open, Learning and Share
Welcome To Ask or Share your Answers For Others

Categories

0 votes
538 views
in Technique[技术] by (71.8m points)

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

In the synopsis of git reset:

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

I have an issue with the markers' meaning.

I know [] stands for options, <> stands for replacement. But, what's the meaning of ()? If there's no |, are the parentheses still needed?

I didn't find relative clues in POSIX Utility Conventions.

See Question&Answers more detail:os

与恶龙缠斗过久,自身亦成为恶龙;凝视深渊过久,深渊将回以凝视…
Welcome To Ask or Share your Answers For Others

1 Reply

0 votes
by (71.8m points)

This is covered in git's CodingGuidelines, found on their Github. It gives contributors a style guide while also describing how help options should be written. Other sources like POSIX or BSD should not be taken as authoritative, especially since they don't always conform to POSIX1. The following excerpt is near the bottom of the file:

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.

1: The following excerpt is at the top of the file:

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.


与恶龙缠斗过久,自身亦成为恶龙;凝视深渊过久,深渊将回以凝视…
OGeek|极客中国-欢迎来到极客的世界,一个免费开放的程序员编程交流平台!开放,进步,分享!让技术改变生活,让极客改变未来! Welcome to OGeek Q&A Community for programmer and developer-Open, Learning and Share
Click Here to Ask a Question

...