utilities/ovs-command-bashcomp.INSTALL.md

   1 Using bash command-line completion scripts
   2 ------------------------------------------
   3
   4 There are two completion scripts available, ovs-appctl-bashcomp.bash
   5 and ovs-vsctl-bashcomp.bash respectively.
   6
   7 ovs-appctl-bashcomp
   8 -------------------
   9
  10    ovs-appctl-bashcomp.bash adds bash command-line completion support
  11    for ovs-appctl, ovs-dpctl, ovs-ofctl and ovsdb-tool commands.
  12
  13    Features:
  14    ---------
  15
  16       display available completion or complete on unfinished user input
  17       (long option, subcommand, and argument).
  18
  19       once the subcommand (e.g. ofproto/trace) has been given, the
  20       script will print the subcommand format.
  21
  22       the script can convert between keywords like 'bridge/port/interface/dp'
  23       and the available record in ovsdb.
  24
  25    Limitations:
  26    ------------
  27
  28       only support small set of important keywords
  29       (dp, datapath, bridge, switch, port, interface, iface).
  30
  31       does not support parsing of nested options
  32       (e.g. ovsdb-tool create [db [schema]]).
  33
  34       does not support expansion on repeatitive argument
  35       (e.g. ovs-dpctl show [dp...]).
  36
  37       only support matching on long options, and only in the format
  38       (--option [arg], i.e. should not use --option=[arg]).
  39
  40 ovs-vsctl-bashcomp
  41 -------------------
  42
  43    ovs-vsctl-bashcomp.bash adds bash command-line completion support
  44    for ovs-vsctl command.
  45
  46    Features:
  47    ---------
  48
  49       display available completion and complete on user input for
  50       global/local options, command, and argument.
  51
  52       query database and expand keywords like 'table/record/column/key'
  53       to available completions.
  54
  55       deal with argument relations like 'one and more', 'zero or one'.
  56
  57       complete multiple ovs-vsctl commands cascaded via '--'.
  58
  59    Limitations:
  60    ------------
  61
  62       completion of very long ovs-vsctl command can take up to several
  63       seconds.
  64
  65 How to use:
  66 -----------
  67
  68    To use the scripts, either copy them inside /etc/bash_completion.d/ or
  69    manually run it directly in bash via . ovs-appctl-bashcomp.bash or
  70    . ovs-vsctl-bashcomp.bash.
  71
  72 Test:
  73 -----
  74
  75    Unit tests are added in tests/completion.at and integrated into autotest
  76    framework.  To run the tests, just do make check.
  77
  78 Bug Reporting:
  79 --------------
  80
  81 Please report problems to bugs@openvswitch.org.