8.6 Programmable Completion
When word completion is attempted for an argument to a command for
which a completion specification (a compspec) has been defined
complete builtin (see section 8.7 Programmable Completion Builtins),
the programmable completion facilities are invoked.
First, the command name is identified.
If a compspec has been defined for that command, the
compspec is used to generate the list of possible completions for the word.
If the command word is a full pathname, a compspec for the full
pathname is searched for first.
If no compspec is found for the full pathname, an attempt is made to
find a compspec for the portion following the final slash.
Once a compspec has been found, it is used to generate the list of
If a compspec is not found, the default Bash completion
described above (see section 8.4.6 Letting Readline Type For You) is performed.
First, the actions specified by the compspec are used.
Only matches which are prefixed by the word being completed are
-d option is used for filename or
directory name completion, the shell variable
used to filter the matches.
See section 5.2 Bash Variables, for a description of
Any completions specified by a filename expansion pattern to the
-G option are generated next.
The words generated by the pattern need not match the word being completed.
GLOBIGNORE shell variable is not used to filter the matches,
FIGNORE shell variable is used.
Next, the string specified as the argument to the
The string is first split using the characters in the
special variable as delimiters.
Shell quoting is honored.
Each word is then expanded using
brace expansion, tilde expansion, parameter and variable expansion,
command substitution, arithmetic expansion, and pathname expansion,
as described above (see section 3.5 Shell Expansions).
The results are split using the rules described above
(see section 3.5.7 Word Splitting).
The results of the expansion are prefix-matched against the word being
completed, and the matching words become the possible completions.
After these matches have been generated, any shell function or command
specified with the
-C options is invoked.
When the command or function is invoked, the
COMP_POINT variables are assigned values as described above
(see section 5.2 Bash Variables).
If a shell function is being invoked, the
COMP_CWORD variables are also set.
When the function or command is invoked, the first argument is the
name of the command whose arguments are being completed, the
second argument is the word being completed, and the third argument
is the word preceding the word being completed on the current command line.
No filtering of the generated completions against the word being completed
is performed; the function or command has complete freedom in generating
Any function specified with
-F is invoked first.
The function may use any of the shell facilities, including the
compgen builtin described below
(see section 8.7 Programmable Completion Builtins), to generate the matches.
It must put the possible completions in the
Next, any command specified with the
-C option is invoked
in an environment equivalent to command substitution.
It should print a list of completions, one per line, to
the standard output.
Backslash may be used to escape a newline, if necessary.
After all of the possible completions are generated, any filter
specified with the
-X option is applied to the list.
The filter is a pattern as used for pathname expansion; a '&'
in the pattern is replaced with the text of the word being completed.
A literal '&' may be escaped with a backslash; the backslash
is removed before attempting a match.
Any completion that matches the pattern will be removed from the list.
A leading '!' negates the pattern; in this case any completion
not matching the pattern will be removed.
Finally, any prefix and suffix specified with the
options are added to each member of the completion list, and the result is
returned to the Readline completion code as the list of possible
If the previously-applied actions do not generate any matches, and the
-o dirnames option was supplied to
complete when the
compspec was defined, directory name completion is attempted.
By default, if a compspec is found, whatever it generates is returned to
the completion code as the full set of possible completions.
The default Bash completions are not attempted, and the Readline default
of filename completion is disabled.
-o default option was supplied to
complete when the
compspec was defined, Readline's default completion will be performed
if the compspec generates no matches.
When a compspec indicates that directory name completion is desired,
the programmable completion functions force Readline to append a slash
to completed names which are symbolic links to directories, subject to
the value of the mark-directories Readline variable, regardless
of the setting of the mark-symlinked-directories Readline variable.