New Ticket     Tickets     Wiki     Browse Source     Timeline     Roadmap     Ticket Reports     Search
Last modified 9 days ago Last modified on 08/22/16 01:35:30

<- Back to the HOWTO section

How to use bash-completion

  • Audience: All users
  • Requires: -


bash-completion is a set of bash scripts which enables customized completion for specific commands.

This is not just for files and directories, but also e.g. for the commands of port. So you type port <Tab> and get a list of all possible commands.


Step 1: Install bash-completion

$ sudo port install bash-completion

Step 2: Enable bash-completion in your .bash_profile

You have to add bash-completion to your .profile or .bash_profile.

First, locate the file you are using. If there is a .bash_profile edit this file, if there is only .profile you want to edit this. If neither file exists create .bash_profile.

Open the file in any editor and add the following lines. Make sure you add this after any PATH manipulation as otherwise the bash-completion will not work correctly.

# bash-completion
if [ -f /opt/local/etc/profile.d/ ]; then
    . /opt/local/etc/profile.d/

Important: Reopen your Terminal afterwards.

Step 3: Use bash from MacPorts in your terminal

The port bash-completion at version 2.0 requires at least bash at version 4.1; the older bash 3.2 provided by Apple with Mac OS X is not compatible anymore with this version. Please make sure you are using /opt/local/bin/bash by changing the preferences of your terminal accordingly. If your version of bash is too old, the script above will not modify your shell environment and no extended completion will be available.

You need to change the command uses to launch the shell in the preferences.

  1. Menu > Preferences > Startup, "Shells open with:"
  2. Select "Command" and enter /opt/local/bin/bash -l to switch to bash provided by MacPorts.
  3. Menu > Preferences > Settings > Shell (per shell type), "Prompt before closing:"
  4. Click "+" and add "bash" to the list of processes (in newer versions of OS X use "-bash").
  5. Close and reopen any terminal windows


You need to change the command iTerm2 uses to launch the shell in the appropriate profile in the preferences.

  1. Menu > Preferences > Profiles tab
  2. Select your profile, on the right switch to the General tab, see "Command"
  3. Select "Command:" and enter /opt/local/bin/bash -l
  4. Close and reopen any terminal windows

Add /opt/local/bin/bash to the file /etc/shells, otherwise it will be impossible to use AppleScript to tell Terminal to execute scripts (like 'osascript -e "tell application \"Terminal\" to do script \"echo hello\""').

Optional Parts

Install +bash_completion variant automatically with all ports

Open the file /opt/local/etc/macports/variants.conf in any editor and add a new line:


From now on, MacPorts will automatically select the bash_completion variant for all ports if available.

Additional Modifications

For some tools you need additional configuration as they rely on the login shell instead of using what the Terminal started. You can export SHELL=/opt/local/bin/bash to the environment, which is respected by both tmux and screen. Alternative configuration is shown below.


For screen, you need to set shell /opt/local/bin/bash in your .screenrc.


For tmux, you need to set set -g default-shell "/opt/local/bin/bash" in your .tmux.conf.

<- Back to the HOWTO section