Consistent cmd option order?

[jorgeorpinel]

Extracted from #3608 (comment)

To match docs, where options have been ordered manually from more to less important (at least that's the idea).

Example difference:

λ dvc commit -h
usage: dvc commit [-h] [-q | -v] [-f] [-d] [-R] [targets [targets ...]]
...

optional arguments:
  -h, --help            show this help message and exit
  -q, --quiet           Be quiet.
  -v, --verbose         Be verbose.
  -f, --force      Commit even if hash value for dependencies/outputs changed.
  -d, --with-deps  Commit all dependencies of the specified target.
  -R, --recursive  Commit cache for subdirectories of the specified directory.

(DVC 0.93.0)

vs. https://dvc.org/doc/command-reference/commit#options:

[jorgeorpinel]

I'm wondering whether -h -q -v can be moved to the bottom of all cmd -h outputs as a first step..

[efiop]

@jorgeorpinel They probably could be moved with some hack or something, but I would urge you to consider if this is really worth it.

[efiop]

@jorgeorpinel I guess worth elaborating that moving -h/-v would require a non-trivial hack for argparse, which is probably too much effort for this kind of change. Not as easy as moving few lines around, unfortunately 🙁

[jorgeorpinel]

Yes, -h -q -v def. don't seem worth trying to move. I'm not sure about the other ones though, let's say you have 20 lines in your terminal vertically (most people will have more but still) you use -h on a big command like run and scroll back to the top of the output. Shouldn't the more commonly used options be shown first? It could potentially save time and make the experience a little better.

It's probably marginal so I'm not obsessing over this or anything. We can just leave it open and if we never get to it just close it at some point. Or close it if you feel strongly against this, np on my side 🙂

[efiop]

@jorgeorpinel Those are really good points! If we look at it that way, maybe it is worth hacking it at some point. Also, interesting to note that things like awscli don't even use argparse and use their own implementation to be able to polish the experience. I don't have a strong opinion.

[efiop]

@jorgeorpinel how about we just sort in alphabetical order to start with? The "commonly used" approach is a nice extension, but it will require collecting some stats and is only really relevant for long help. So, for example, for dvc -h, where we have all of the commands and where indeed it might be nice to have commonly-used ones more visible.

[jorgeorpinel]

Sure, that's a reasonable approach which simplifies maintaining core and docs @efiop.

only really relevant for long help

Also agree, although long help probably covers all the most important commands and like 80% of the help text overall so not sure that if we ever implement that it's worth discriminating.

[shcheklein]

how about we just sort in alphabetical order to start with?

tbh, I would prefer to keep them in some reasonable order, at least on the docs side (important to less important, or in some cases there should be blocks that cluster related things, e.g. --all-commits, --all-branches.). We def can see auxiliary options like (-q/h/v) and most important options specific to the command.

sorting alphabetical sounds like random to me