--help not very helpful

[jalanb]

When asking for help about pyupgrade with the option --help I see

$ pyupgrade --help
usage: pyupgrade [-h] [--exit-zero-even-if-changed] [--keep-percent-format] [--keep-mock] [--keep-runtime-typing] [--py3-plus] [--py36-plus] [--py37-plus] [--py38-plus]
                 [--py39-plus] [--py310-plus] [--py311-plus] [--py312-plus]
                 [filenames ...]

positional arguments:
  filenames

options:
  -h, --help            show this help message and exit
  --exit-zero-even-if-changed
  --keep-percent-format
  --keep-mock
  --keep-runtime-typing
  --py3-plus, --py3-only
  --py36-plus
  --py37-plus
  --py38-plus
  --py39-plus
  --py310-plus
  --py311-plus
  --py312-plus

This is not very helpful to a pyupgrade-newbie like me, because the options are not explained at all. I'm left wondering what (e.g.) --keep-mock does, and why might I use it. Which format does --keep-percent-format effect? Might be the old percent formats for strings, but who knows?

In particular the actual upgrade options are confusing: why is it (e.g.) called --py37-plus, and not just --py37? Is it going to upgrade the options beyond what is needed for Python 3.7? This question is further confused by there being -plus and -only variants for the --py3 option. Why does that one get a -only variant, but none of the others do?

As there is no other documentation of what these options mean, e.g. on GitHub readme or other, I think the exact meaning of these options should be explicitly laid out in the --help text.

[asottile]

In particular the actual upgrade options are confusing: why is it (e.g.) called --py37-plus, and not just --py37

they both work

As there is no other documentation of what these options mean, e.g. on GitHub readme or other

you clearly haven't read the readme so I'm going to decline this