Where is the `--` (double dash) argument documented?

Question

There are some utilities that accept a -- (double dash) as the signal for "end of options", required when a file name starts with a dash:

$ echo "Hello World!" >-file

$ cat -- -file
Hello World!

$ cat -file                      # cat - -file fails in the same way.
cat: invalid option -- 'f'
Try 'cat --help' for more information.

But some of those utilities don't show such an option in the manual page.

The man page for cat doesn't document the use (or validity) of a -- argument in any of the OS'es. This is not meant to be a Unix - Linux flame war, it is a valid, and, I believe, useful concern.

Neither cat, mv, ed (and I am sure many others) document such an option in their manual page that I can find.

Note that ./-file is a more portable workaround to the use of --. For example, the source (dot) command (and written as .) doesn't (generally) work well with an -- argument:

$ echo 'echo "Hello World!"' >-file

$ . ./-file
Hello World!

$ . -file
ksh: .: -f: unknown option
ksh: .: -i: unknown option
ksh: .: -l: unknown option
ksh: .: -e: unknown option
Usage: . [ options ] name [arg ...]

$ . -- -file         # works in bash. Not in dash, ksh, zsh.
ksh: .: -file: cannot open [No such file or directory]

Answer 1

This is a POSIX requirement for all utilities, see POSIX chapter 12.02, Guideline 10 for more information:

The first -- argument that is not an option-argument should be accepted as a delimiter indicating the end of options. Any following arguments should be treated as operands, even if they begin with the '-' character.

POSIX recommends all utilities to follow these guidelines.

There are a few exceptions like echo (read at OPTIONS). And special builtins that do not follow the guidelines (like break, dot, exec, etc.) :

Some of the special built-ins are described as conforming to XBD Utility Syntax Guidelines. For those that are not, the requirement in Utility Description Defaults that "--" be recognized as a first argument to be discarded does not apply and a conforming application shall not use that argument.

The intent is to document all commands that do not follow the guidelines in their POSIX man page, from POSIX chapter 12.02 third paragraph:

Some of the standard utilities do not conform to all of these guidelines; in those cases, the OPTIONS sections describe the deviations.

As the cat POSIX man page documents no deviations in the OPTIONS section, it is expected that it accept -- as a valid argument.

There still may be (faulty) implementations that fail to follow the guideline.

In particular, most GNU core utilities follow this guideline

Answer 2

For Linux OS that have a GNU userland: Debian, RedHat, Ubuntu, Mint, etc. (not some BSD's) the GNU common practices are important:

The list of utilities in your question have in common that they are GNU, in fact they all are GNU coreutils. The full GNU coreutils list is longer.

Most of the utilities from GNU share a common user interface and a common set of basic command line options like --help, --version and the use of -- as the signal for end of options.

The entry at info common and the GNU web page contain:

Certain options are available in all of these programs. Rather than writing identical descriptions for each of the programs, they are described here. (In fact, every GNU program accepts (or should accept) these options.)

‘--’
Delimit the option list. Later arguments, if any, are treated as operands even if they begin with ‘-’. For example, ‘sort -- -r’ reads from the file named -r.

A more precise (but not that easy to explain and remember) command to get to the -- entry is (please copy exactly) info -- cat --.

Answer 3

It is also documented in getopt(1) and getopt(3).

For example,

Each parameter after a `--' parameter is always interpreted as a non-option parameter.

Answer 4

-- signals the end of options and disables further option processing, it is the part of a shell you use.

The same like man cat does not describe that space is delimiter between command options, because it is described in manual to your shell.

What shell do you use, /bin/bash ? So the answer to you question is man bash, because it is explained there as part of shell functionality, it is not a part of a command functionality.

---

Updated: This is Incorrect

Thank you for correcting me. The things I mentioned are correct for most of built-in shell commands (except if it is mentioned otherwise in manual). But in case of external commands, it is about POSIX conventions.