[wiki:howto <- Back to the HOWTO section]

= How to use bash-completion =

 * Audience: All users
 * Requires: -

== Introduction ==

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.

== Installation ==

=== 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/bash_completion ]; then
    . /opt/local/etc/bash_completion
fi
}}}
Important: Reopen your Terminal afterwards.

Important: The port bash-completion >=2.0 requires bash >=4.1; please make sure you are using ${prefix}/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.

And you are done. From now on, you are able to use customized bash-completion. 

== 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:
{{{
+bash_completion
}}}

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

[wiki:howto <- Back to the HOWTO section]