如何阅读git手册，方括号和尖括号的区别

Linux/Unix man page syntax conventions

In man pages I come across various syntaxes to write Linux/Unix commands, which include square brackets, angular brackets, hyphens (-) and double hyphens (--) in various combinations. Does anyone know the meaning of these syntax conventions?

[ ]
< >
[< >]
[--]
-
--
[< >...]

 

回答

Square Brackets [ ]

The square brackets ( [ ] ) indicate that the enclosed element (parameter, value, or information) is optional. You can choose one or more items or no items. Do not type the square brackets themselves in the command line.

Example: [global options], [source arguments], [destination arguments]

Angle Brackets < >

The angle brackets ( < > ) indicate that the enclosed element (parameter, value, or information) is mandatory. You are required to replace the text within the angle brackets with the appropriate information. Do not type the angle brackets themselves in the command line.

Example: -f [set the File Name variable], -printer <printer name>, -repeat <months> <days> <hours> <minutes>, date access <mm/dd/yyyy>

In Unix-like systems, the ASCII hyphen–minus is commonly used to specify options. The character is usually followed by one or more letters. An argument that is a single hyphen–minus by itself without any letters usually specifies that a program should handle data coming from the standard input or send data to the standard output. Two hyphen–minus characters ( -- ) are used on some programs to specify "long options" where more descriptive option names are used. This is a common feature of GNU software.

Just do 'ls --help' and look at the options, it should be obvious to you.

 -A, --almost-all           do not list implied . and ..
     --author               with -l, print the author of each file
 -b, --escape               print octal escapes for nongraphic characters
     --block-size=SIZE      use SIZE-byte blocks
 -B, --ignore-backups       do not list implied entries ending with ~
 -c                         with -lt: sort by, and show, ctime (time of last
                              modification of file status information)
                              with -l: show ctime and sort by name
                              otherwise: sort by ctime'
 -C                         list entries by columns
     --color[=WHEN] 

 

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

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 POSIX¹. 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.

¹: 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.

 

作者:Chuck Lu    GitHub