Description of problem: "virsh help" has several issues. 1) it emits all of the help in detail, which is a) different behaviour than e.g. git or subversion does and b) results in spilling out lots of text which scrolls through any terminal size. Overview is lost and grep is your friend again... We would suggest to output only the help sections domain <short description> monitor <short description> host <short description> interface <short description> ... and only upon "virsh help domain" to emit the domain commands overview. As the domain names are different from the command names anyway, e.g. "virsh help create" would still work as is. 2) The sorting is inconsistent Alphabetical sorting is ok, but please make sure it stays that way. There is no reason to have "emulatorpin" between "vcpupin" and "vncdisplay" vcpupin control or query domain vcpu affinity emulatorpin control or query domain emulator affinity vncdisplay vnc display also, there is no reason to have "connect" after "quit" quit quit this interactive terminal connect (re)connect to hypervisor Version-Release number of selected component (if applicable): happens in # virsh version Compiled against library: libvirt 1.2.9 Using library: libvirt 1.2.9 Using API: QEMU 1.2.9 Running hypervisor: QEMU 2.1.2 as well as in # virsh version Compiled against library: libvirt 1.3.0 Using library: libvirt 1.3.0 Using API: QEMU 1.3.0 Running hypervisor: QEMU 2.5.0 How reproducible: Steps to Reproduce: 1. virsh help 2. observe Actual results: too much text, inconsistent output Expected results: toplevel overview; consistent output in detail overview Additional info:
I strongly like the way the help output dumps every command: I like to be able to do 'virsh help | grep part-of-the-command-name-that-i-remember' or similar. The proposed subsection bit is more code and requires multiple commands if a user just wants to browse the whole help output. Regarding the sorting... it seems like within disparate categories some of the commands are grouped logically rather than strictly alphabetically. Like the two pin commands above. They should have probably been named pin-vcpu and pin-emulator for better alphabetic consistency. I agree it's confusing but I wouldn't be surprised if a patch to the list generates some bike shedding :) I think for these issues it's better to just say 'please send a patch to libvir-list' than track them here. Closing as DEFERRED