Replace query option --order_results with --order_output, which can take three values for a given output formatter: 'no', 'deps', or 'full'. A fourth value, 'auto', means either 'deps' or 'full' depending on the formatter.

The option 'no' is equivalent to --noorder_results. 'full' means that output will be deterministically ordered, using alphabetization if necessary. 'deps' means that graph order will be preserved (where applicable), but further efforts to order the output may not be undertaken. 'auto' is equivalent to 'full' for all output formatters except for proto, minrank, maxrank, and graph, for which it is equivalent to 'deps'.

The purpose of this cl is to enable genquery to force completely deterministic output, which requires that it be able to specify a total ordering on the graph that is consistent across runs. Which ordering doesn't matter very much, so depending on the output formatter, or even within the same one, there may be some groups of nodes that are ordered alphabetically, and some reverse alphabetically.

--
MOS_MIGRATED_REVID=101512292

1 files changed, 30 insertions, 14 deletions

diff --git a/site/docs/query.html b/site/docs/query.html
index 1e36492a8e..38b0642f53 100644
--- a/site/docs/query.html
+++ b/site/docs/query.html
@@ -1394,25 +1394,41 @@ genrule(
   conservation of graph order</a>", <i>presenting</i> the results may be done
   in either a dependency-ordered or unordered manner. This does <b>not</b>
   influence the targets in the result set or how the query is computed. It only
-  affects how the results are printed to stdout. The
-  <code>--[no]order_results</code> flag can be used to control this behavior.
+  affects how the results are printed to stdout. Moreover, nodes that are
+  equivalent in the dependency order may or may not be ordered alphabetically.
+  The <code>--order_output</code> flag can be used to control this behavior.
+  (The <code>--[no]order_results</code> flag has a subset of the functionality
+  of the <code>--order_output</code> flag and is deprecated.)
 </p>
 <p>
-  When <code>--order_results</code> is used (this is the default), then the
-  graph order will be preserved in the output. For example the query
-  <code>deps(x)</code> will print the dependencies of target <code>x</code>
-  before printing <code>x</code> itself.
+  The default value of this flag is <code>auto</code>, which is equivalent to
+  <code>full</code> for every output format except for <code>proto</code>,
+  <code>graph</code>, <code>minrank</code>, and <code>maxrank</code>, for which
+  it is equivalent to <code>deps</code>.
 </p>
 <p>
-  When <code>--noorder_results</code> is used and <code>--order</code> is one
-  of <code>label</code>, <code>label_kind</code>, <code>location</code>,
-  <code>package</code>, <code>proto</code>, <code>record</code> or
-  <code>xml</code>, the outputs will be printed in arbitrary order. <b>This is
-  generally faster than using <code>--order_results</code></b>. It is not
-  supported though when <code>--order</code> is one of <code>graph</code>,
+  When this flag is <code>no</code> and <code>--order</code> is one of
+  <code>build</code>, <code>label</code>, <code>label_kind</code>,
+  <code>location</code>, <code>package</code>, <code>proto</code>,
+  <code>record</code> or <code>xml</code>, the outputs will be printed in
+  arbitrary order. <b>This is generally the fastest option</b>. It is not
+  supported though when <code>--output</code> is one of <code>graph</code>,
   <code>min_rank</code> or <code>max_rank</code>: with these formats, bazel will
-  ignore the <code>--[no]order_results</code> flag and always print ordered
-  results.
+  always print results ordered by the dependency order or rank.
+</p>
+<p>
+  When this flag is <code>deps</code>, bazel will print results ordered by the
+  dependency order. However, nodes that are unordered by the dependency order
+  (because there is no path from either one to the other) may be printed in any
+  order.
+</p>
+<p>
+  When this flag is <code>full</code>, bazel will print results ordered by the
+  dependency order, with unordered nodes ordered alphabetically or reverse
+  alphabetically, depending on the output format. This may be slower than the
+  other options, and so should only be used when deterministic results are
+  important &mdash; it is guaranteed with this option that running the same query
+  multiple times will always produce the same output.
 </p>
 
 <h3 id="output-label">Print the label of each target</h3>