Why does my ls --help not work?

Question

Marias-MacBook-Air:~ marias$ ls --help

ls: illegal option -- -

usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]

Answer 1

The ls version in Mac OS X is based on BSD ls, and doesn't support long-format options including --help. See the ls manpage or man ls on your system for details.

Answer 2

Different commands support different option styles. The major trends are:

• getopt(): getopt() is a 30 year old programming API to parse options. It's widely available and the only POSIX standard.

  It only supports single letter options some of which can take arguments. Several options can be combined together for brevity.

  Example: tail -fn -2: an argument-less option (-f) followed by -n that takes an argument of -2 (can also be written tail -fn-2 or tail -f -n -2). -- is used to mark the end of options.

• XrmParseCommand(): (80's) called for instance from XtOpenApplication().

  The API used by traditional (read old-style nowadays) X11 applications. There, options are single arguments, typically and traditionally -option (or +option).

  Options can take arguments, but cannot be combined like for getopt() (even if defined as single letter options like -d for a short for -display).

• GNU getopt_long. (late 80's). GNU extended the getopt() API to add support for long options in a compatible way.

  GNU is the origin of those --long options and the reason why they're very common on GNU systems and not so much elsewhere.

  There, you have two types of options: long and short. The long ones are --foo. Those that take arguments can be written either --foo=arg or --foo arg.

  Another extension is options that can optionally take arguments (-o or -oarg, --opt or --opt=arg), though the short variant doesn't allow passing an empty argument. Long options can also be abbreviated. As in instead of --help, you can pass --he or --h (provided it's the only option that starts with h). GNU option parsing also allows intertwining option and non-option arguments (though -- can still be used to mark the end of options).

  That GNU-style of options is now becoming a new de-facto standard, with most languages having an API to parse them (sometimes with not the full feature-set, sometimes with extensions).

• The wild west: now many applications do the parsing of their options by hand, or use less common libraries that have yet another syntax. Unless they seek conformance to a standard, there's nothing stopping them from doing whatever they want. And of course, some commands don't take options at all.

Now whether any command has any option to print a help or usage message is also totally at the discretion of the application writer.

Many applications will print a usage message when an option is not recognised (for those commands that take options). Some may print a message upon -h, -?, -help, --help, --usage, --long-help...

Now, calling a command with a random argument, not knowing what that may do is a dangerous business. -h may be for help or anything else. For instance shutdown -h is to halt the system. -help would be short for -h -e -l -p (or -h -e lp or -h elp as in --host=elp...) for a command that uses getopt() or getopt_long()...

If you know a command accept options, a relatively safe bet is -? or -:. In a shell:

cmd -\?
cmd -:

For the getopt() API, the : and ? have a special meaning so are unlikely to be valid options. You'd then get an error message which may give you a hint at what a valid option to get help if any might be.

$ xterm -:
xterm: bad command line option "-:"

usage:  xterm [-/+132] [-C] [-Sccn] [-T string] [-/+ah] [-/+ai] [-/+aw]
[...]

Type xterm -help for a full description.
$ dd -:
dd: invalid option -- ':'
Try 'dd --help' for more information.
$ ls -:
ls: illegal option -- :
usage: ls -1RadCxmnlogrtucpFbqisfL [files]

Won't work with every command.

In any case, your best bet is to try man first as already mentioned.

Beware that some commands are shell builtins (try type the-command to find out), so the documentation for them will be found in your shell's manual.

That's generally not the case of ls though.