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    The bashcomp scripts should be placed at /etc/bash_completion.d/
  69    to be available for all bash sessions.  Running 'make install'
  70    will place the scripts to $(sysconfdir)/bash_completion.d/.  So user
  71    should specify --sysconfdir=/etc at configuration.  Meanwhile, if OVS is
  72    installed from packages, the scripts will automatically be placed inside
  73    /etc/bash_completion.d/.
  74
  75    If you just want to run the scripts in one bash, you can remove them from
  76    /etc/bash_completion.d/ and run the scripts via '. ovs-appctl-bashcomp.bash'
  77    or '. ovs-vsctl-bashcomp.bash'.
  78
  79 Test:
  80 -----
  81
  82    Unit tests are added in tests/completion.at and integrated into autotest
  83    framework.  To run the tests, just do make check.
  84
  85 Bug Reporting:
  86 --------------
  87
  88 Please report problems to bugs@openvswitch.org.