[PATCH 0/2] rev-list --disk-usage example docs

On Thu, Feb 11, 2021 at 01:04:26PM +0100, Ævar Arnfjörð Bjarmason wrote:

quoted

I think this is the "narrowly scoped" bit from Junio's response above.
It would be a bit weird to have an examples section for rev-list that
only mentions this rather obscure feature.

I don't think the lack of an EXAMPLES section or the relative obscurity
of the switch should preclude us from adding useful documentation.

Yes it would feel a bit out of place, but we can always have a
sub-section of EXAMPLES, and we've got to start somewhere.

Fair enough. Here are some patches (to go on top of jk/rev-list-disk-usage,
though obviously the first one could be applied independently).

In this case I don't see why it couldn't be added to OPTIONS, we've got
some very long discussion there already, and as long as there's a clear
separation in prose from an initial brief discussion of the switch and
further prose it won't be confusing for readers, they can just page past
the details.

It's already big and scary enough that I prefer starting an EXAMPLES
section. :)

By the way, there's one other finishing touch we might consider:
enabling --use-bitmap-index automatically when bitmaps are present, for
requests that produce the identical answer (so _not_ a regular
traversal, because the output order and presence of pathnames are
different there). I'd prefer to do that as a separate series, though,
since there are multiple arguments that might benefit (like --count).

  [1/2]: docs/rev-list: add an examples section
  [2/2]: docs/rev-list: add some examples of --disk-usage

 Documentation/git-rev-list.txt | 93 ++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)

-Peff