Kelly Kaoudis, kelly.n.kaoudis at intel.com, June 2015

Setting Up NVMe Tab Autocompletion for bash or zsh
==================================================

If your working shell is bash...
--------------------------------
the following gets bash autocompletion to behave properly
#echo "bind 'set show-all-if-ambiguous on'" >> ~/.bashrc
#echo "bind 'set show-all-if-unmodified on'" >> ~/.bashrc
#echo "bind 'set completion-ignore-case on'" >> ~/.bashrc
#echo "bind 'set completion-map-case on'" >> ~/.bashrc

add NVMe autocompletion script to your autocompletes directory
#cp `pwd`/bash-nvme-completion.sh /etc/bash_completion.d/nvme

make sure this bash knows where everything is
#source /etc/bash_completion.d/nvme && source ~/.bashrc

you should be able to autocomplete with the nvme utility now
(double TABs still apply)! If autocompleting has disappeared,
just re-source nvme and .bashrc. To see a full list of auto-completable
NVMe commands, type "nvme help " and hit TAB.

You may also need to uncomment the "enable bash completion in interactive
shells" part of /etc/bash.bashrc, which hopefully looks something like:

if [ -f /usr/share/bash-completion/bash_completion ]; then
	. /usr/share/bash-completion/bash_completion
elif [ -f /etc/bash_completion ]; then
	. /etc/bash_completion
fi

(don't bother with the shopt part, your Bash version might not support shopt).

Bash footnote: for bash vers >= 4.2, it appears to be the case that
menu-complete **no longer works.** If the bash dev folks ever re-patch this,
try binding TAB to menu-complete to cycle through the NVMe subcommand matches
on whatever you typed.

if your working shell is zsh...
-------------------------------
create the zsh completions directory if you don't have it
#if [ ! -e "~/.zsh" ]; then
#	mkdir ~/.zsh
#	mkdir ~/.zsh/completion
#fi

#cp `pwd`/_nvme ~/.zsh/completion/_nvme

add compinit if you don't have it in your .zshrc
#echo "autoload -Uz compinit && compinit" >> ~/.zshrc

add nvme autocompletions to your .zshrc
#echo "# source for tab autocompletions" >> ~/.zshrc
#echo "fpath=(~/.zsh/completion $fpath)" >> ~/.zshrc
#echo "source ~/.zsh/completion/_nvme" >> ~/.zshrc

make sure this zsh knows where everything is
#source ~/.zsh/completion/_nvme && source ~/.zshrc

You should be able to autocomplete with the nvme utility now (single TAB press
should get you a completion with descriptions -- sadly, bash doesn't support
descriptions within completions). If autocompletes disappear, just re-source
_nvme and .zshrc. Also, make sure your .zshrc is ordered correctly: we want to
source _nvme before updating our fpath. Both of these should occur before
compinit is loaded.

Updating NVMe Tab Autocompletions
=================================

zsh
---

Add your new command to the _cmds array in the following format:

'command:short-form description'

Add a case to the zsh case statement for autocompletion of subopts
in the following format (as seen in _nvme):

(bar)
	local _list_of_subopts
	_list_of_subopts=(
	/dev/nvme':supply a device to use (required)'
	--foo':do something cool'
	-f':alias of --foo'
	)

	_arguments '*:: :->subcmds'
	_describe -t commands "nvme bar options" _list_of_subopts
	;;

All zsh autocompletion built-ins start with _, and so should anything
internal to your autocompletes. _arguments and _describe are built-ins.
The '*:: :->subcmds' bit describes the format in which we want our
options to be displayed (don't change this, unless you like pain.)
_describe -t adds our list of options to the data structure associated with
our command `bar'.

Add the name of your command to the (help) case as well.

Update your ~/.zsh/completion/_nvme with your new changes and re-source as needed.

bash
----

Add the name of your command to _cmds in bash_nvme_completion.sh. Add a case to
_nvme_list_opts in the following format:

"bar")
opts+="--foo= -f --baz= -b"
;;

Update your /etc/bash_completion.d/nvme version, and re-source things as needed.

TO DO
-----
Automatically generate man pages and autocompletions for new NVMe commands, possibly
with kerneldoc.