1

I am looking for some sort of "syntax key" for command line tools on GNU/Linux, something like this document that Microsoft has:

https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/command-line-syntax-key.

For instance, text inside square brackets is used in Microsoft command line syntax documentation to represent optional items. Text in square braces is a set of required items and you must choose one. And so forth.

What are the symbols used to indicate command line syntax in GNU/Linux, and what does each symbol mean?

  • That syntax key is a key/legend for other documentation—if you want the shell syntax, you should read the man page for the shell you use (bash, dash, zsh, etc.). For specific utilities, again, man pages. – D. Ben Knoble Sep 15 '19 at 17:58
  • If you want to know how the man command describes things then man man will describe the man command. – X Tian Sep 25 '19 at 9:06
  • 1
    @XTian, take a look at man man and just read the "synopsis" section, and pretend you didn't already understand what the square brackets and vertical bars are supposed to mean. It would be (and is for beginners) utterly baffling. This is a great question; I've edited to make the essence of it more clear. – Wildcard Sep 25 '19 at 9:28
  • 1
    POSIX has a section about this called "Utility Argument Syntax": pubs.opengroup.org/onlinepubs/9699919799/basedefs/… – Kusalananda Sep 25 '19 at 11:46
1

Here is an excerpt from man 7 man-pages, which describes the conventional meanings for sections within man pages:

   SYNOPSIS      A brief summary of the command or function's interface.

                 For commands, this shows the syntax of  the  command  and
                 its  arguments  (including options); boldface is used for
                 as-is text and italics are used to  indicate  replaceable
                 arguments.   Brackets  ([])  surround optional arguments,
                 vertical bars (|) separate choices,  and  ellipses  (...)
                 can  be  repeated.

I will add that how "boldface" and "italics" actually appear on your terminal is a different question. On my terminal, I get boldface for the as-is text and underlined text for the replaceable arguments; and on some terminals you may not get any such formatting at all.

The keynote is:

  • Optional items are enclosed in square brackets
  • Vertical bars separate choices
  • Ellipses mean an item or element can be repeated

Overall, the conventions are in fact very similar to the document from Microsoft that you cite.

Here is an example synopsis, from the man page for git diff:

SYNOPSIS
       git diff [options] [<commit>] [--] [<path>...]
       git diff [options] --cached [<commit>] [--] [<path>...]
       git diff [options] <commit> <commit> [--] [<path>...]
       git diff [options] <blob> <blob>
       git diff [options] [--no-index] [--] <path> <path>

The possible options are so numerous that the man page authors decided not to list them all in the synopsis, instead just saying [options].

The multiple lines in the synopsis are because there are multiple possible (mutually exclusive) ways to use this particular command.

Everything in square brackets is optional, and everything in angle brackets is a placeholder.

(N.B.: Commits and blobs are types of objects that can be stored in Git; a blob represents a file's contents and a commit represents a state of the entire set of files being tracked by Git. Not germane to your question but I'm mentioning this to avoid a mystery on terminology.)

Another example, the synopsis of the grep command, illustrates another convention: words written in ALL CAPS are sometimes used to show a placeholder (like the angle brackets in the git man page above).

SYNOPSIS
       grep [OPTIONS] PATTERN [FILE...]
       grep [OPTIONS] -e PATTERN ... [FILE...]
       grep [OPTIONS] -f FILE ... [FILE...]

Here, again, there are three different ways to call the grep command. From reading the above, you can see that:

grep apple orange pear

...means that apple is the pattern and orange and pear are both file names.

Likewise, you can see that in:

grep -e apple -e orange pear grapefruit

...apple and orange are both patterns, and pear and grapefruit are both files.

Now as for what that means in terms of what the command will do when given patterns and files, you have to read more of the man page than just the synopsis. But the synopsis lets you determine how the various arguments will be interpreted by the command you're giving them to.

There are no absolute rules for the synopsis symbols, though. Here is the synopsis for sed:

SYNOPSIS
       sed [OPTION]... {script-only-if-no-other-script} [input-file]...

To make complete sense of that, you need to read further in the man page, where you will find:

   If no -e, --expression, -f, or --file option is given, then  the  first
   non-option  argument  is  taken  as  the  sed script to interpret.  All
   remaining arguments are names of input files; if  no  input  files  are
   specified, then the standard input is read.
0

man man shows you the manual page for the manual, here follows an extract explaining the conventions used,

   The following conventions apply to the SYNOPSIS section and can be used
   as a guide in other sections.

   bold text          type exactly as shown.
   italic text        replace with appropriate argument.
   [-abc]             any or all arguments within [ ] are optional.
   -a|-b              options delimited by | cannot be used together.

   argument ...       argument is repeatable.
   [expression] ...   entire expression within [ ] is repeatable.

   Exact rendering may vary depending on the output device.  For instance,
   man will usually not be able to render italics when running in a termi‐
   nal, and will typically use underlined or coloured text instead.

   The command or function illustration is a pattern that should match all
   possible invocations.  In some cases it is advisable to illustrate sev‐
   eral exclusive invocations as is shown in the SYNOPSIS section of  this
   manual page.
-1

I am not sure what you are asking for exactly. I give three examples to show you are right:

 Pipelines
       A pipeline is a sequence of one or more commands separated by 
       one of thwe control operators | or |&. The format for a pipeline is:
       [time [-p]] [ ! ] command [ [|||&] command2 ... ]

(from Bash Manual; type man bash in your shell)

In bash.pdf from GNU, containing some subtle changes:

The format for a pipeline is
[time [-p]] [!]command1[ | or |&command2] ...

And in the posix specification :

The format for a pipeline is:
    [!] command1 [ | command2 ...]

The shell alone uses so many special characters that a consistent meta syntax is not practical. But they all use the same usual suspects.

A "shell" is not a "command line", and GNU/Linux is not MS, so the differences add up. You probably first need some basic info on using a linux shell and on unix in general - surely there is info on the web exactly for your situation. GNU/Linux does not feel responsible for explaining the basics or the differences to windows.

Another example, with the find command / utility

man find gives this in GNU/Linux shell bash:

  find  [-H]  [-L] [-P] [-D debugopts] [-Olevel] [starting-point...] [ex-
   pression]

When you enter /EXPR in man's pager (or just read on and scroll), you arrive at

EXPRESSION
       The  part  of the command line after the list of starting points is the
       expression.  This is a kind of query specification ...[cut]

which takes you to:

 OPERATORS
       Listed in order of decreasing precedence:

       ( expr )
              Force  precedence.   Since parentheses are special to the shell,
              you will normally need to quote them.  Many of the  examples  in
              this manual page use backslashes for this purpose: `\(...\)' in-
              stead of `(...)'.

And all this can lead to an elaborate little "kind of query" like:

find -L /students/projects/myname \
    -type d '(' -name '.aaa' -o -name '*rc*' ')' -prune -o \
    -path '*/*/class_project/*/*/pikachu/*/*/bambi/b‌​ambi.txt' -print

This searches for all "bambi.txt" in certain subfolders, skipping other certain subfolders...it needs () to express: "prune (skip), if it is a folder and the name is either .aaa or contains rc".

And then the parens need to be protected from interpretation by the shell, by using single quotes or backslash. Most of the time the -o for OR and default -a for AND is enough, so GNU/Linux lives with it.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.