11

How exactly do you have to interpret the output of a commands "usage" output, in bash for example.

For example, on my OS X, cp gives me

usage: cp [-R [-H | -L | -P]] [-fi | -n] [-apvX] source_file target_file
       cp [-R [-H | -L | -P]] [-fi | -n] [-apvX] source_file ... target_directory
  • What does the nested options, like -H within -R, indicate?
  • Does upper and lower case have any meaning?
  • When is an argument optional, required?

I need to implement a telnet command line against a program of mine and I would like to get this straight.

Insyte
  • 9,314
  • 2
  • 27
  • 45
raoulsson
  • 4,633
  • 10
  • 32
  • 29

2 Answers2

15

For anyone trying to understand what usage output means, the best way is to man man.

seriously :-) Take the time to learn the conventions, it really helps.

   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.
Justin
  • 3,776
  • 15
  • 20
  • +1 deleting my post as redundant. – Warner Mar 24 '10 at 04:55
  • `man man` on CentOS 6.6 doesn't have this section; nor does the version of `man man` on Mac OS X 10.7.4. Where can I find it? – Wildcard Mar 04 '16 at 22:23
  • Found it, it's `man man-pages` in CentOS and `man manpages` on Mac OS X (which uses BSD commands). – Wildcard Mar 05 '16 at 01:59
  • This answer, as well as the `man man` command doesn't seem to cover cases where the input must be one of the items in an enumeration. For example ` - must be one of [dev | test | uat | perf | prod]` – Addison Jul 11 '17 at 05:24
2

First of all, while there are general conventions, they are not uniformly applied.

  • In this case, it's saying that if you use -R (indicating "recursion"), then you can use either -H, -L, or -P. If you don't use -R, then those options are not relevant.
  • Yes, case is almost always important. So usually -h and -H do completely different things.
  • The square brackets generally indicate that an option or argument is "optional". (The things with hyphens in front of them are "options", the words without hyphens are arguments.) Without brackets the option or argument is generally required. In your example, both "source_file" and "target_directory" are required. The "..." indicates that the previous argument can be repeated.

Other points worth noting:

  • The vertical bar indicates "OR". So [-fi | -n] indicates you can use either -f and/or -i but not in combination with -n.
  • Grouped options in brackets indicate you can use any of them. So [-apvX] indicates you can use any combination of those options. They don't even need to be smashed together. So -a -v -p would be a valid combination.
Insyte
  • 9,314
  • 2
  • 27
  • 45