bash-completion

Introduction

bash-completion is a collection of command-line completion recipes for a number of commands for the completion system of the Bash shell. These recipes enhance Bash's typical plain completion of filenames to provide better suggestions of options and arguments for many commands. Also provided is a collection of helper functions to assist in creating new recipes, and a set of facilities for loading recipes automatically on demand, as well as installing them.

Installation

The easiest way to install this software is to use a package; refer to Repology for a comprehensive list of operating system distributions, package names, and available versions.

Depending on the package, you may still need to source it from either /etc/bashrc or ~/.bashrc (or any other file sourcing those). If you have only bash >= 4.2 installed, you can do this by using:

# Use bash-completion, if available, and avoid double-sourcing
[[ $PS1 &&
  ! ${BASH_COMPLETION_VERSINFO:-} &&
  -f /usr/share/bash-completion/bash_completion ]] &&
    . /usr/share/bash-completion/bash_completion

If you have older bash versions in use, their loading of bash_completion should be prevented. See further for more info.

If you don't have the package readily available for your distribution, or you simply don't want to use one, you can install bash-completion using the standard commands for GNU autotools packages:

autoreconf -i      # if not installing from prepared release tarball
./configure
make               # GNU make required
make check         # optional
make install       # as root
make installcheck  # optional, requires python3 with pytest >= 3.6, pexpect

These commands install the completions and helpers, as well as a profile.d script that loads bash_completion where appropriate.

If your system does not use the profile.d directory (usually below /etc) mechanism (i.e., does not automatically source shell scripts in it), you can source the $sysconfdir/profile.d/bash_completion.sh script in /etc/bashrc or ~/.bashrc.

The profile.d script provides a configuration file hook that can be used to prevent loading bash_completion on a per user basis when it's installed system wide. To do this:

1. Turn off programmable completion with shopt -u progcomp in $XDG_CONFIG_HOME/bash_completion (or ~/.config/bash_completion if $XDG_CONFIG_HOME is not set)
2. Turn it back on (for example in ~/.bashrc) if you want to use programmable completion for other purposes.

macOS (OS X)

If you're using macOS (formerly OS X), /etc/bashrc is apparently not sourced at all, and ~/.bashrc is not sourced from ~/.bash_profile by default (because ~/.bash_profile is not created by default). In this case, the standard way is to configure ~/.bash_profile to source ~/.bashrc and write interactive settings in ~/.bashrc. You can source ~/.bashrc in ~/.bash_profile in the following way:

# ~/.bash_profile

if [[ -f ~/.bashrc ]]; then
  source ~/.bashrc
fi

Then, you can source bash-completion in your ~/.bashrc. It should be noted that bash-completion should not be sourced in ~/.bash_profile because ~/.bash_profile is only loaded in interactive login shell sessions. If you start nested Bash sessions, the interactive settings in ~/.bash_profile will disappear. It is strongly recommended to source ~/.bashrc from ~/.bash_profile and write interactive settings in ~/.bashrc.

For example, if you install bash-completion using Homebrew, it will install the entry point of bash-completion to $HOMEBREW_PREFIX/etc/profile.d/bash_completion.sh. You can source it by adding the following to your startup file ~/.bashrc:

if [[ -s $HOMEBREW_PREFIX/etc/profile.d/bash_completion.sh ]]; then
  . "$HOMEBREW_PREFIX/etc/profile.d/bash_completion.sh"
fi

Troubleshooting

If you find that a given function is producing errors or does not work as it should under certain circumstances when you attempt completion, try running set -x or set -v prior to attempting the completion again. This will produce useful debugging output that will aid us in fixing the problem if you are unable to do so yourself. Turn off the trace output by running either set +x or set +v.

If you are filing an issue, please attach the generated debugging output in set -x mode copy-pasted to a separate, attached file in the report. Before doing so, be sure to review the output for anything you may not want to share in public, and redact as appropriate.

To debug dynamic loading of a completion, tracing needs to be turned on before the debugged completion is attempted the first time. The easiest way to do this is to start a new shell session, and to turn tracing on in it before doing anything else there.

Known problems

1. Many of the completion functions assume GNU versions of the various text utilities that they call (e.g. grep, sed, and awk). Your mileage may vary.

FAQ

Q1. The bash-completion code inhibits some commands from completing on files with extensions that are legitimate in my environment. Do I have to disable completion for that command in order to complete on the files that I need to?

A. No. If needed just once in a while, use M-/ to (in the words of the bash man page) attempt file name completion on the text to the left of the cursor. This will circumvent any file type restrictions put in place by the bash completion code. If needed more regularly, see the next question:

Q2. How can I override a completion shipped by bash-completion or install a new completion for a user account?

A. To override a completion for a specific command, you can install your own completion file for the command into an appropriate place. It will take precedence over the one shipped by us or the one installed systemwide. To install a completion on per user basis, put the completion file at <userdir>/completions/<cmd>.bash, where <cmd> is the command name and <userdir> is one of the user directories. The user directories are specified by the colon-separated $BASH_COMPLETION_USER_DIR (defaults to $XDG_DATA_HOME/bash-completion, or ~/.local/share/bash-completion if $XDG_DATA_HOME is not set). They will be loaded automatically on demand when the respective command is being completed.

[!NOTE] See also the answer to Q4 for considerations for those files' names, they apply here as well.

Completion settings that should be loaded on initialization of bash-completion should be defined in a startup completion file. A startup completion file can be added in the directory <userdir>/startup (see the previous paragraph for <userdir>). A prefix of the form [0-9][0-9][0-9]_ may be prepended to the filename of the startup files to control the loading order. To override a existing startup file installed systemwide or shipped by us, you can put your own version with the same filename in <userdir>/startup. In identifying the overridden startup file, the prefixes [0-9][0-9][0-9]_ are ignored. If you want to disable a startup completion file, you can use an empty file.

You can also define eagerly loaded settings in the user file (${BASH_COMPLETION_USER_FILE:-$HOME/.bash_completion}). Instead of preparing separate files for specific commands, you may write completion settings for specific commands directly in the user file. When you want to modify the default completion setting set by complete -D (which is available in Bash >= 4.1), you can override it in the user file or in a user startup file. If you want to use bash's default completion instead of one of ours, in the user file or in a user startup script, you can define something like this:

complete -o default -o bashdefault $cmd

where $cmd is the command to override completion for.

Q3. How can I override a completion shipped by bash-completion systemwide?

A. Install a local completion appropriately for the desired command, and it will take precedence over the one shipped by us.

A completion file for a specific command <cmd> can be placed at <localdir>/completions/<cmd>.bash, where <localdir> is /usr/local/share/bash-completion if XDG_DATA_DIRS is not defined, or <datadir>/bash-completion where <datadir> is one of the directories listed in XDG_DATA_DIRS.

[!NOTE] See also the answer to Q4 for considerations for those files' names, they apply here as well.

Similarly, systemwide startup files can be placed in the directory <localdir>/startup.

Q4. I author/maintain a distribution package and would like to maintain my own completion code for this package. Where should I put it to be sure that interactive bash shells will find it and source it?

[!NOTE] Here, how to make the completion code visible to bash-completion is explained. We do not require always making the completion code visible to bash-completion. In what condition the completion code is installed should be determined at the author/maintainers' own discretion.

A. Install it in one of the directories pointed to by bash-completion's pkgconfig file variables.

• The recommended directory for the completions of specific commands is <completionsdir>, which you can get with `pkg-