refs: add a '--required' flag to 'git refs optimize'

At GitLab, we use a transaction manager in Gitaly (our service layer on top of Git) to manage incoming requests. This provides snapshotting capabilities and provides ACID properties. To optimize for performance, read snapshots are shared. This means they are cheaper to initiate than write snapshots. However, housekeeping requires a write snapshot.

Currently, we run housekeeping in write snapshots, which includes optimizing references. If Git exposed information regarding if optimization was required, then we could spawn a read snapshot to check if optimization was required and only spawn a write snapshot if needed.

This patch series adds a '--required' flag to 'git refs optimize' which will indicate if optimization is required for the reference backend or not.

The series is structured as follows:

Patches 1-4 are mostly clean-up patches, cleaning up existing code post the addition of 'git refs optimize'. Some of them could be potentially dropped.

Patch 5 fixes the test which checks for inconsistent leading whites paces in our documentation for built-in commands to also consider subcommands.

Patches 6-8 are preliminary patches which add the required changes to provide a functionality which only checks if optimization is required without running it.

Patch 9 adds the '--required' flag.

The series is based on top of 60f3f52f (The sixteenth batch, 2025-10-08) with 'ps/ref-peeled-tags' merged in.

Closes: #562