compgen
Generate command completion suggestions
TLDR
List all commands that you could run
List all commands that you could run that start with a specified string
List all aliases
List all functions that you could run
Show shell reserved keywords
See all available commands/aliases starting with 'ls'
List all users on the system
Display help
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.