This document attempts to explain the basic styles and patterns that are used in the bash completion. New code should try to conform to these standards so that it is as easy to maintain as existing code. Of course every rule has an exception, but it’s important to know the rules nonetheless!

This is particularly directed at people new to the bash completion codebase, who are in the process of getting their code reviewed. Before getting a review, please read over this document and make sure your code conforms to the recommendations here.

Indent step should be 4 spaces, no tabs.

Avoid "fancy" globbing in case labels, just use traditional style when possible. For example, do "--foo|--bar)" instead of "--@(foo|bar))". Rationale: the former is easier to read, often easier to grep, and doesn’t confuse editors as bad as the latter, and is concise enough.

Always use [[ ]] instead of [ ]. Rationale: the former is less error prone, more featureful, and slightly faster.

Try to wrap lines at 79 characters. Never go past this limit, unless you absolutely need to (example: a long sed regular expression, or the like). This also holds true for the documentation and the testsuite. Other files, like ChangeLog, or COPYING, are exempt from this rule.

When you need to do some code substitution in your completion script, you MUST use the $(…) construct, rather than the `…`. The former is preferable because anyone, with any keyboard layout, is able to type it. Backticks aren’t always available, without doing strange key combinations.

As a rule of thumb, do not use "complete -o filenames". Doing it makes it take effect for all completions from the affected function, which may break things if some completions from the function must not be escaped as filenames. Instead, use "compopt -o filenames" to turn on "-o filenames" behavior dynamically when returning completions that need that kind of processing (e.g. file and command names). The _filedir and _filedir_xspec helpers do this automatically whenever they return some completions.

The above is functionally a shorthand for:

if [[ ${#COMPREPLY[@]} -eq 1 && ${COMPREPLY[0]} == *= ]]; then
    compopt -o nospace
fi

It is used to ensure that long options' name won’t get a space appended after the equal sign. Calling compopt -o nospace makes sense in case completion actually occurs: when only one completion is available in COMPREPLY.

Should be used in completions using the -s flag of _init_completion, or other similar cases where _split_longopt has been invoked, after $prev has been managed but before $cur is considered. If $cur of the form --foo=bar was split into $prev=--foo and $cur=bar and the $prev block did not process the option argument completion, it makes sense to return immediately after the $prev block because --foo obviously takes an argument and the remainder of the completion function is unlikely to provide meaningful results for the required argument. Think of this as a catch-all for unknown options requiring an argument.

Note that even when using this, options that are known to require an argument but for which we don’t have argument completion should be explicitly handled (non-completed) in the $prev handling block because --foo=bar options can often be written without the equals sign, and in that case the long option splitting does not occur.

The bash-completion package contains an automated test suite. Running the tests should help verifying that bash-completion works as expected. The tests are also very helpful in uncovering software regressions at an early stage.

The original, "legacy" bash-completion test suite is written on top of the DejaGnu testing framework. DejaGnu is written in Expect, which in turn uses Tcl — Tool command language.

Most of the test framework has been ported over to use pytest and pexpect. Eventually, all of it should be ported.

For the Python part, all of it is formatted using Black, and we also run Flake8 on it.

The legacy test suite tries to adhere to this Tcl Style Guide.

Installing dependencies should be easy using your local package manager or pip. Python 3.4 or newer is required, and the rest of the Python package dependencies are specified in the test/requirements.txt file. If using pip, this file can be fed directly to it, e.g. like:

pip install -r test/requirements.txt

sudo apt-get install python3-pytest python3-pexpect dejagnu tcllib

sudo yum install python3-pytest python3-pexpect dejagnu tcllib

Pytest tests are in the t/ subdirectory, with t/test_\*.py being completion tests, and t/unit/test_unit_\*.py unit tests.

Legacy tests are grouped into different areas, called tool in DejaGnu:

Python based tests are run by calling pytest on the desired test directories or individual files, for example in the project root directory:

pytest test/t

Legacy tests are run by calling runtest command in the test directory:

runtest --outdir log --tool completion
runtest --outdir log --tool install
runtest --outdir log --tool unit

The commands above are already wrapped up in shell scripts within the test directory:

./runCompletion
./runInstall
./runUnit

To run a particular test, specify file name of your test as an argument to runCompletion script:

./runCompletion ssh.exp

That will run test/completion/ssh.exp.

See test/docker/docker-script.sh for how and what we run and test in CI.