Convention of parameter naming - undocumented options

Question

GNU has long pushed for a combination of short options (-h) and long options (--help), which goes a long way to clearing up the syntactical mess of commands like tar and dd, with their legacy syntax going back to the stone age.

But I recently learned that GNU's parted has a third kind of option, where an 'undocumented feature' can be accessed with ---pretend-input-tty. It looks like it was introduced in this commit in 2007.

It's the first time I've seen that, and I'm intrigued. Is this some kind of wider convention, or just a one-off?

Answer 1

Undocumented long options starting with 3 dashes is indeed widespread in software from the GNU project. It's not mentioned in the GNU coding standards though as far as I can tell.

Other examples from grepping for {"-.*argument in the C files in the source tree of a few GNU software bundles:

coreutils/src/du.c:  /* {"-debug", no_argument, nullptr, FTS_DEBUG}, */
coreutils/src/factor.c:  {"-debug", no_argument, nullptr, DEV_DEBUG_OPTION},
coreutils/src/head.c:  {"-presume-input-pipe", no_argument, nullptr,
coreutils/src/numfmt.c:  {"-debug", no_argument, nullptr, DEV_DEBUG_OPTION},
coreutils/src/rm.c:  {"-presume-input-tty", no_argument, nullptr, PRESUME_INPUT_TTY_OPTION},
coreutils/src/split.c:  {"-io-blksize", required_argument, nullptr,
coreutils/src/stty.c:  {"-debug", no_argument, nullptr, DEV_DEBUG_OPTION},
coreutils/src/tail.c:  {"-disable-inotify", no_argument, nullptr,
coreutils/src/tail.c:  {"-presume-input-pipe", no_argument, nullptr,
diffutils/src/diff.c:  {"-no-directory", no_argument, nullptr, NO_DIRECTORY_OPTION},
diffutils/src/diff.c:  {"-presume-output-tty", no_argument, nullptr, PRESUME_OUTPUT_TTY_OPTION},

Among those, the oldest I could find from a cursory look at the git logs was tail's ---disable-inotify (mentioned in a few Q&As here) which was added in 2009.

commit 526a057602f7f312443ae4ec0653fec84bca9ff2
Author: Pádraig Brady <[email protected]>
Date:   Fri Sep 4 21:41:30 2009 +0100

    tests: test old tail -f method even on systems with inotify

    * src/tail.c (main): Add an undocumented ---disable-inotify option

In any case an undocumented option is one that is not committed on and could disappear without warning in a future version. Using that ---option convention is nice in that it's a reminder that it's not one that is here to stay.

There are also undocumented single-letter options such as the -X of GNU grep or options that have another undocumented alias for compatibility with other implementations like the --text/--binary of GNU cksum.

Some started of as undocumented such as the -E of GNU sed (for compatibility with BSD, GNU having -r instead), but ended up being documented later on (in the case of sed's -E because that's the one that ended up being specified by POSIX and it's also arguably a much better one as it's consistent with grep -E and E for Extended makes much more sense than r for regex).