zq "-query" flag mentioned in docs but doesn't exist

[philrz]

tl;dr

The zq docs mention a -query flag that doesn't appear to have ever existed. It seems we should either implement it or remove reference to it from the docs.

Details

At the time this issue is being filed, Zed is at commit 87deeeb.

The text in question is from the zq usage docs after describing the heuristic approach for determining whether the first argument is a query or an input.

This heuristic is convenient but can result in a rare surprise when a simple Zed query (like a keyword search) happens to correspond with a file of the same name in the local directory. To avoid this, you can provide the query with the -query flag, which specifies the Zed program to run and forces all arguments to be interpreted as inputs.

The text in question was first introduced as part of #3722, but compiling zq at the commit associated with that PR doesn't show the flag as existing then and it doesn't appear to have been introduced since. But it does seem like its existence could be justified since the "surprise" still seems to exist as described. For instance, starting with this directory and single input file:

$ ls -l
total 8
-rw-r--r--  1 phil  staff  29 Feb 27 16:27 input

$ cat input 
{"foo": "bar"}
{"baz": "in"}

$ zq -version
Version: v1.14.0-6-g87deeebe

$ zq in input 
{baz:"in"}

$ echo '{"hello": "world"}' > in

$ zq in input 
{hello:"world"}
{foo:"bar"}
{baz:"in"}

Per the docs, to disambiguate that last example it seems like zq -query in input would be a reasonable way to return just the {baz:"in"} result despite the existence of the file named in.

The wider context in which I happened to be revisiting these docs is brainstorming with @mattnibs on improvements related to #5046. I was reviewing the docs for possible improvements we could make and came across this -query option as something that we might be able to recommend in zq error outputs, only to find it doesn't exist.