LinuxCommandLibrary

compgen

Generate command completion suggestions

TLDR

List all commands that you could run

$ compgen -c
copy

List all commands that you could run that start with a specified string
$ compgen -c [str]
copy

List all aliases
$ compgen -a
copy

List all functions that you could run
$ compgen -A function
copy

Show shell reserved keywords
$ compgen -k
copy

See all available commands/aliases starting with 'ls'
$ compgen -ac [ls]
copy

List all users on the system
$ compgen -u
copy

Display help
$ compgen --help
copy

SYNOPSIS

compgen [options] [word]

PARAMETERS

-a
    Generate completion for alias names.

-b
    Generate completion for built-in commands.

-c
    Generate completion for command names (includes aliases, functions, built-ins).

-d
    Generate completion for directory names.

-e
    Generate completion for exported shell variable names.

-f
    Generate completion for file names.

-g
    Generate completion for command group names.

-j
    Generate completion for job names.

-k
    Generate completion for shell keyword names.

-l
    Generate completion for login names.

-m
    Generate completion for mount point names.

-o option
    Apply a named completion option (e.g., default, filenames, nospace).

-p
    Generate completion for command pathnames found in $PATH.

-r
    Generate completion for readonly shell variable names.

-s
    Generate completion for service names (requires /etc/services).

-t
    Generate completion for tags (requires ctags support).

-u
    Generate completion for user names.

-v
    Generate completion for all shell variable names (includes exported and readonly).

-A action
    Apply a completion action (e.g., command, file, variable, user) to the generated list.

-G globpat
    Filter the generated list using a glob pattern.

-P prefix
    Add a prefix to each generated completion word.

-S suffix
    Add a suffix to each generated completion word.

-W wordlist
    Generate completion from a space-separated wordlist.

-F function
    Execute function to generate completions, typically for complex logic.

-C command
    Execute command to generate completions, similar to -F but uses an external command.

-X filterpat
    Filter the generated list using an extended pattern (shell pattern matching).

-V varname
    Generate completion using the contents of shell variable varname as a wordlist.

word
    The optional word to complete; compgen only outputs matches beginning with this word. If omitted, all possible completions are generated.

DESCRIPTION

compgen is a Bash built-in command designed to generate possible completion words based on specified criteria. It serves as the core engine for programmable completion, primarily utilized by the complete built-in. Unlike actual completion, compgen outputs a list of matching words to standard output, which can then be processed or filtered before being presented to the user by Bash's completion system. This allows for highly customized and intelligent tab-completion behaviors. It supports a wide array of options to define the type of completions, such as commands, keywords, aliases, built-ins, functions, variables, files, and directories. Furthermore, it can apply patterns for matching, specify word lists, and handle prefixes. This flexibility makes compgen an indispensable tool for scripting sophisticated completion rules, enhancing user productivity by streamlining command-line interactions. It effectively transforms complex completion logic into a manageable and extensible system within the shell environment.

CAVEATS

compgen is a Bash built-in command, meaning it is not a standalone executable. Its primary purpose is to generate raw completion lists for the complete built-in, and its output is typically not formatted for direct user consumption. The effectiveness of certain options (e.g., -s for services, -t for tags) depends on the underlying system configuration and presence of specific files or tools (like /etc/services or ctags).

TYPICAL USAGE WITH <I><CODE>COMPLETE</CODE></I>

compgen is most frequently used within a completion function that is registered with the complete built-in, to populate the COMPREPLY array.

For example, to provide specific words for a command 'mycommand':

_my_command_completion() {
  COMPREPLY=( $(compgen -W "alpha beta gamma" -- "$1") )
}
complete -F _my_command_completion mycommand

This setup makes 'alpha', 'beta', and 'gamma' available for tab completion after typing 'mycommand '.

HISTORY

Programmable completion capabilities, including the compgen built-in, were introduced in Bash 2.0, released in 1996. This marked a significant enhancement, allowing users to define highly customized tab-completion rules beyond simple filename expansion. compgen provided the core logic for generating completion candidates, separating this functionality from the rule definition handled by complete. It has since remained a fundamental and stable component of Bash's advanced completion system, evolving alongside the shell to support new features and completion types.

SEE ALSO

complete(1), compopt(1), bash(1)

Copied to clipboard