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.
Use [[ $x ]] and [[ ! $x ]] instead of [[ -n $x ]] and [[ -z $x ]],
and similarly with the test builtin.
Rationale: no strong technical reasons to prefer either style, but the former
is subjectively slightly more readable and it was traditionally more common in
the codebase before this style item was standardized.
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 backticks. 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
fiIt 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 _comp_initialize,
or other similar cases where _comp__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.
When dealing with numeric data, take advantage of arithmetic evaluation.
In essence, use (( ... )) whenever it can replace [[ ... ]] because the
syntax is more readable; no need for $-prefixes, numeric comparison etc
operators are more familiar and easier on the eye.
Array subscripts are arithmetic expressions, take advantage of that.
E.g. write ${foo[bar]}, not ${foo[$bar]}, and similarly ${foo[bar+1]}
vs ${foo[((bar+1))]} or ${foo[$((bar+1))]}, ${foo[--i]} vs
${foo[((--i))]}.
Use i, j, k for loop-local indices; n and m for lengths; some other
descriptive name typically based on array name but in singular when looping
over actual values. If an index or value is to be accessed later on instead of
being just locally for looping, use a more descriptive and specific name for
it.
See API and naming.
To avoid unexpected word splitting and pathname expansions, an argument of
commands needs to be properly quoted when it contains shell expansions such as
$var, $(cmd), and $((expr)).
When one intentionally wants word splitting and pathname expansions, one should
consider using the utility functions provided by bash-completion. To safely
split a string without being affected by non-standard IFS and pathname
expansions, use the shell function _comp_split. To safely obtain filenames
by pathname expansions without being affected by failglob, etc., use the
shell function _comp_expand_glob. Note that _comp_expand_glob should be
always used for the pathname patterns even if the pattern does not contain
shell expansions.
In the following contexts, the quoting to suppress word splitting and pathname expansions are not needed.
- The right-hand sides of variable assignments ...
v=WORD(e.g.v=$var) - The arguments of conditional commands ...
[[ WORD ]](e.g.[[ $var ]]) - The argument specified to
casestatement ...case WORD in foo) ;; esac(e.g.case $var in foo) ;; esac)
In bash-completion, we do not quote them by default. However, there are exceptions where the quoting is still needed for other reasons.
- When the word directly contains shell special characters (space, tab,
newline, or a character from
;|&()<>\\$`'"#!~{), these characters need to be quoted. The "directly" means that the special characters produced by shell expansions are excluded here. For example, when one wants to include a whitespace as a part of the value of the word, the right-hand side can be quoted asv="a b". - An empty word (i.e., the word whose value is an empty string) is specified by
"". The right-hand side of an assignment technically can be an empty string asvar=, but we still usevar=""there becauseshellchecksuggests that e.g.var= cmdis confusing withvar=cmd. $*and${array[*]}need to be always quoted because they can be affected by the word splitting in bash <= 4.2 even in the above contexts.- In the following contexts, double-quoting of shell expansions is needed
unless the result of expansions is intentionally treated as glob patterns or
regular expressions.
- The right-hand sides of
==,!=, and=~in the conditional commands ...[[ word == "$var" ]] - The case patterns ...
case word in "$var") ;; esac
- The right-hand sides of
Note: Here strings cat <<<$var are also supposed to be safe against word
splitting and pathname expansions without quoting, but bash <= 4.3 has a bug
[1], so they need to be quoted for as long as we support bash 4.3.
There are also preferences on the type of quoting, which are though not too
strict. We prefer to use double quotes over single quotes by default. When
the value contains $, `, \, and ", we can use single quotes to
avoid backslash escaping or use the one that minimizes the use of backslash
escaping. When the value contains control characters such as a tab and a
newline, we do not directly include them but we use backslash escape sequences
such as \t and \n in the escape string $'...'.
There is a subtlety in quoting of the array expansions with a pattern
replacement when shopt -s patsub_replacement (Bash >= 5.2) is
enabled (which is the default of Bash >= 5.2).
For example, the array expansions with a pattern replacement may be used to add a prefix to every element in an array:
# problem in bash >= 5.2
arr=("${arr[@]/#/$prefix}")However, this has the problem. The characters & contained in
$prefix, if any, will be replaced with the matched string. The
unexpected patsub_replacement may be suppressed by quoting the
replacement as
# problem with bash <= 4.2 or "shopt -s compat42"
arr=("${arr[@]/#/"$prefix"}")However, this has another problem in bash < 4.3 or when shopt -s compat42 is turned on. The inner double quotations are treated
literally so that the PREFIX instead of ``"PREFIX"is prefixed to elements. To avoid this situation, the outer double quotations might be removed, but this has even another problem of the pathname expansions andIFS`.
Specifically for prefixing and suffixing, we may instead use
_comp_compgen -- -P prefix and _comp_compgen -- -S suffix.
# solution for prefixing
_comp_compgen -Rv arr -- -P "$prefix" -W '"${arr[@]}"'In a general case, one needs to modify each array element in a loop, where only the replacement is quoted.
# general solution
for i in "${!arr[@]}"; do
arr[i]=${arr[i]//pat/"$rep"}
done