1 files changed, 120 insertions, 0 deletions
diff --git a/completions/README b/completions/README
new file mode 100644
index 0000000..ba1032a
--- /dev/null
+++ b/completions/README
@@ -0,0 +1,120 @@
+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.