Rust Version

1.55.0

Affected Version of clap

v3.0.0-beta.4

Expected Behavior Summary

Args are ordered as I declare them

Actual Behavior Summary

Args are sorted, without any exception (exceptions are common)

Context

DeriveDisplayOrder is a very popular flag to turn on. When further researching this, it is popular across CLIs and even when args are sorted, its one manually to allow exceptions.

rg is one major exception for this

I don't enable DeriveDisplayOrder because I do actually want everything to be alphabetical. See group command line args into affected processing steps BurntSushi/ripgrep#1814 and organized flags in man page according to logical section? BurntSushi/ripgrep#1022 for more details.

I chalk this up to rg being an exceptional case in its scope and design and being limited by clap2's lack of help_heading.

Trade offs

Current Sorting Implementation

• Strengths
  • Immediate polish for quick and dirty programs
  • Maintainable polish with large CLIs that have no good sort order and can't use help_heading (ie rg)
• Weaknesses
  • Doesn't group --no- flags with their positive versions
  • Sorts all, even --help and --version which are generally left unsorted

Deriving Order

• Easily discoverable path to both behaviors (can manually sort without finding the Setting)
  • Except when composing CLIs, like with #[clap(flatten)]
• Commonly what is expected

Survey of CLIs

Sorted

• rg
  • sort order is always respected, even for --help and --version (uses clap, author confirmed its intentional)
• tokei
  • sort order is always respected, even for --help and --version (uses clap)
• gnu ls
  • sort order is broken for --help / --version
• gnu df
  • sort order is broken for --help / --version
• less
  • sorts by short name, then long name (so long names without a short name are last)
  • Even sorts no- variants

Custom

• cargo
• bat
• fd
• delta
• hyperfine
• rsync
• vim
• gnu chmod
  • Even if this was sorted, I suspect the no- variants would not be sorted
• mount
• curl
• wget
• iptables
• traceroute
• gnu grep
• gnu find (mostly sorted but there are exceptions

(List of commands was inspired by prior Rust command list, some off the top of my head, and a random 50 linux command list I found. I only did a random sampling of the GNU CoreUtils though)