59

By reading this question, I have discovered that GNU grep has a -X option which expects an argument. Strangely, it is mentioned neither in the man page nor in the info page.

Looking at the source code, there is that comment right in the middle of the --help output:

/* -X is deliberately undocumented.  */

Looking further, it appears that the -X matcher option sets the engine used for the regexp, matcher being one of grep, egrep, fgrep, awk, gawk, posixawk and perl (as of version 2.25).

Some of those values are strictly identical to existing options (namely grep -G, grep -E, grep -F and grep -P). On the other hand, the three awk variants have no corresponding options.

Does someone know what is the actual purpose of this option, especially with one of the awk regexp engines? Can someone tell me why it is purposely not documented?

Stephen Kitt
  • 411,918
  • 54
  • 1,065
  • 1,164
xhienne
  • 17,075
  • 2
  • 52
  • 68
  • 7
    Interesting discovery! I suspect the purpose of leaving it undocumented is so that they can feel free to remove it from future versions at will and without notice. Another example of a GNU undocumented option is `-E` for GNU sed which provides compatibility with BSD sed. (I expect `-E` to become documented if POSIX formally adopts it and removed if it doesn't.) – John1024 Sep 15 '17 at 01:00
  • 4
    I agree with @John1024, although the only person who can definitively answer is Stepan Kasal, who, on 7 February 2005, documented that `-X` is deliberately undocumented. (His email address is in the changelog if you want to ask him.) – Wildcard Sep 15 '17 at 01:01
  • 3
    I tried to track this down through the git history, but it turns out it was added before grep's first git commit (it was present in 06b9f7e683e7650804cadd9a4c5cf6bff6c89625 from Tue Nov 3 21:38:52 1998). Presumably they imported the previous VCS into git, as obviously that predates git. – derobert Sep 15 '17 at 01:06
  • 1
    Also in grep 2.0 which is the oldest to be found at http://ftp.gnu.org/gnu/grep/?C=M;O=A – derobert Sep 15 '17 at 01:44
  • 4
    ... but not in 1.6 which I found at http://www.oldlinux.org/Linux.old/distributions/TAMU/TAMU-1.0D/src/tar/grep-1.6.tar.gz (note: I have made no effort to verify the authenticity of that code) so it'd appear to date to somewhere between 1.6 (1992) and 2.0 (1993) – derobert Sep 15 '17 at 01:54

1 Answers1

69

Its purpose is to provide access to the various matchers implemented in GNU grep in one form or another, in particular AWK matchers which aren’t available otherwise, probably for testing purposes (see bug 16481 which discusses adding the gawk and posixawk matchers).

However it is currently buggy, which is the reason why it’s documented as being undocumented:

On Thu, Jan 27, 2005 at 04:06:04PM -0500, Charles Levert wrote:
> The '-X' option, and in particular its use with the "awk" matcher
> ("-X awk") is undocumented.

please leave it undocumented.

It doesn't provide any new functionality besides -X awk.

And the implementation of awk regexps is not perfect, I think.

The new GNU regex conatins some means to set AWK style syntax, yes. Yet gawk doesn't use it directly: it parses the regex first.

In particular, awk regexps allow escape sequences \NNN, where NNN is an octal value. So /\040/ mathes space. grep -X awk doesn't seem to support this.

I'm afraid that regex.c doesn't support these escape sequences.

We would have to make sure that the regexes are fully compatible with awk regexes before we decided to document (and thus support) this feature.

I think it's not worth the trouble.

Stepan

A follow-up asked for the comment to be added, and provided a bit more background on the -X option:

My own inclination is to suggest just removing -X entirely. I suspect it was added by the original author mainly for testing purposes. If it's going to stay in, at least add a comment like this.

/* -X is undocumented on purpose. */

to avoid future discussion of a resolved issue.

Arnold

which Stepan did shortly thereafter.

Stephen Kitt
  • 411,918
  • 54
  • 1,065
  • 1,164
  • 4
    Nice archaeological work, thank you Stephen. – xhienne Sep 15 '17 at 07:04
  • 2
    Thanks :-). The trail stops at grep 2.0 unfortunately; I get the impression that’s the version which introduced `-X`, probably as a side-effect of the DFA rewrite, but the changelog is short on details. – Stephen Kitt Sep 15 '17 at 07:16
  • 7
    "to avoid future discussion of a resolved issue." How'd that work out? ;) – Brock Adams Sep 16 '17 at 16:46
  • 1
    Wouldn't "-X is undocumented because it's buggy" have been a better choice? – JAB Sep 17 '17 at 02:48