I was interested in how bash auto-completion works and how to write a custom completer. After about an hour of work, I came up with a solution that at least seems to work on Ubuntu. I now have auto-completion for ArangoDB and all its client tools!

The problem

I use the command-line for almost everything, including starting and stopping ArangoDB and its client tools. They provide lots of options which I cannot completely memorize.

The bash solution for “I don’t know what I am looking for” is to press the TAB key. This will bring up a list of suggestions for how to complete the currently entered word. I thought using the same thing for ArangoDB’s command-line options would be nice, too.

The solution

It turned out that I needed to put a shell script that generates the auto completion for arangod and all the other tools into /etc/bash_completion.d. From there, the system will automatically pick it up when auto-completion is initialized.

The script is rather simple. For example, to have auto-completion for arangosh it would look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

_arangosh()
{
    local cur prev opts
    COMPREPLY=()
    cur="${COMP_WORDS[COMP_CWORD]}"
    prev="${COMP_WORDS[COMP_CWORD-1]}"
    opts="--help --server.endpoint --server.username" # ...all the options go here

    if [[ ${cur} == -* ]] ; then
        COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
        return 0
    fi
}

complete -o default -F _arangosh arangosh

As can be seen, the variable opts should be filled with the list of possible options. Determining the options for a binary can be achieved by invoking it with its --help option, e.g.:

1
2
3
4

arangosh --help | grep -o "^\ \+--[a-z-]\+\(\.[a-z0-9-]\+\)\?" | xargs

# this will generate something like the following output:
# --audit-log --chunk-size --configuration --help --no-auto-complete --no-colors --pager --pretty-print --prompt --quiet --temp-path --use-pager --javascript.check --javascript.current-module-directory --javascript.execute --javascript.execute-string --javascript.gc-interval --javascript.startup-directory --javascript.unit-tests --jslint --log.level --log.use-local-time --server.connect-timeout --server.database --server.disable-authentication --server.endpoint --server.password --server.request-timeout --server.ssl-protocol --server.username

That has to be repeated for all binaries in the ArangoDB package (i.e. arangob, arangosh, arangoimp, arangodump, arangorestore, and arangod).

As the available options might change over time, I wrote a script that extracts them from the binaries and puts together the completions file. This script can be downloaded here for the 2.x branch and here for the 3.x branch. The script expects the already-built ArangoDB binaries to be located in the bin subdirectory. Provided that ArangoDB was compiled from source, this should already be the case.

The script should then be run from the base directory:

1

build-completions-2.sh arangodb

This will write the completions script for all binaries into the file arangodb. Pre-generated completion scripts for various ArangoDB versions can be found here: 2.2 2.3 2.4 2.5 2.6 2.7 2.8 3.0

To activate completions, copy the appropriate file into /etc/bash_completion.d/arangodb. Note that completion may need to be re-initialized once in order to work:

1

. /etc/bash_completion.d/arangodb

Quick setup

The following command should install the completions for 3.0 and activate them:

1
2
3
4

sudo \
  wget -O /etc/bash_completion.d/arangodb \
    https://jsteemann.github.io/downloads/code/completions-3.0 && \
  . /etc/bash_completion.d/arangodb

The following command should install the completions for 2.8 and activate them:

1
2
3
4

sudo \
  wget -O /etc/bash_completion.d/arangodb \
    https://jsteemann.github.io/downloads/code/completions-2.8 && \
  . /etc/bash_completion.d/arangodb

The command for 2.7 is:

1
2
3
4

sudo \
  wget -O /etc/bash_completion.d/arangodb \
    https://jsteemann.github.io/downloads/code/completions-2.7 && \
  . /etc/bash_completion.d/arangodb

(commands are similar for other versions of ArangoDB).

To see it in action, type arangosh -- and then press TAB.

Other environments (MacOS etc.)

Note: I have checked that the above works on Ubuntu and OpenSuSE. I have no idea whether this works with other Linux distributions let alone other shells.

Some Linux/Unix distros do not have /etc/bash_completion.d at all. I was told MacOS is one of them. For such environments, downloading and sourcing the completions script should work:

1
2
3

wget -O ~/arangodb-completions-2.8 \
    https://jsteemann.github.io/downloads/code/completions-2.8
. ~/arangodb-completions-2.8

This will enable the completions in the current shell. To enable them permanently, add the completions script to your .bashrc file:

1

echo ". ~/arangodb-completions-2.8" >> ~/.bashrc