INSTALLATION
------------
The easiest way to install this software is to use a package; it is available
in many operating system distributions. The package's name is usually
bash-completion. Depending on the package, you may still need to source it
from either /etc/bashrc or ~/.bashrc (or any other file sourcing those). You
can do this by simply using:
# Use bash-completion, if available
[[ $PS1 && -f /usr/share/bash-completion/bash_completion ]] && \
. /usr/share/bash-completion/bash_completion
(if you happen to have *only* bash >= 4.1 installed, see further if not)
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:
./configure
make
make check # optional, requires dejagnu and tcllib
make install # as root
These commands installs 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 per user basis when it's
installed system wide. To do this, turn off programmable completion
with "shopt -u progcomp" in $XDG_CONFIG_HOME/bash_completion
(~/.config/bash_completion if $XDG_CONFIG_HOME is not set), and turn
it back on for example in ~/.bashrc if you want to use programmable
completion for other purposes.
If you're using MacOS X, /etc/bashrc is apparently not sourced at all.
In that case, you can put the bash_completion file in /sw/etc and add
the following code to ~/.bash_profile:
if [ -f /sw/etc/bash_completion ]; then
. /sw/etc/bash_completion
fi
TROUBLESHOOTING
---------------
If you find that a given function is producing errors under certain
circumstances when you attempt completion, try running 'set -v' or
'set -x' 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 +v' or 'set +x'.
KNOWN PROBLEMS
--------------
I.
There seems to be some issue with using the bash built-in cd within
Makefiles. When invoked as /bin/sh within Makefiles, bash seems to
have a problem changing directory via the cd command. A work-around
for this is to define SHELL=/bin/bash within your Makefile. This is
believed to be a bug in bash.
II.
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.
III.
If you are seeing 'unbound variable' warnings from bash when hitting
<Tab>, this is because you have either 'set -u' or 'set -o nounset'
somewhere in your start-up files. This causes bash to flag the use of
any uninitialised shell variables as an error.
Whilst we try to avoid references to uninitialised variables in the
code, there seem to be at least some cases where bash issues this
warning even though the variable in question has been initialised.
One place this appears to occur is within the _muttconffiles() helper
function used by mutt completion, where the function calls itself
recursively. This seems to confuse bash and it issues spurious
warnings if 'nounset' is set.
FAQ
---
Q. 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. 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.
Q. How can I insert my own local completions without having to
reinsert them every time you issue a new release?
A. Put them in ~/.bash_completion, which is parsed at the end of the
main completion script. See also the next question.
Q. I author/maintain package X 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?
Install it in one of the directories pointed to by
bash-completion's pkgconfig file variables. There are two
alternatives: the recommended one is 'completionsdir' (get it with
"pkg-config --variable=completionsdir bash-completion") from which
completions are loaded on demand based on invoked commands' names,
so be sure to name your completion file accordingly, and to include
for example symbolic links in case the file provides completions
for more than one command. The other one which is present for
backwards compatibility reasons is 'compatdir' (get it with
"pkg-config --variable=compatdir bash-completion") from which files
are loaded when bash_completion is loaded.
For packages using GNU autotools the installation can be handled
for example like this in configure.ac:
PKG_CHECK_VAR(bashcompdir, [bash-completion], [completionsdir], ,
bashcompdir="${sysconfdir}/bash_completion.d")
AC_SUBST(bashcompdir)
...accompanied by this in Makefile.am:
bashcompdir = @bashcompdir@
dist_bashcomp_DATA = # completion files go here
For cmake we ship the bash-completion-config.cmake and
bash-completion-config-version.cmake files. Example usage:
find_package(bash-completion)
if(BASH_COMPLETION_FOUND)
message(STATUS
"Using bash completion dir ${BASH_COMPLETION_COMPLETIONSDIR}")
else()
set (BASH_COMPLETION_COMPLETIONSDIR "/etc/bash_completion.d")
message (STATUS
"Using fallback bash completion dir ${BASH_COMPLETION_COMPLETIONSDIR}")
endif()
install(FILES your-completion-file DESTINATION
${BASH_COMPLETION_COMPLETIONSDIR})
Q. I use CVS in combination with passwordless ssh access to my remote
repository. How can I have the cvs command complete on remotely
checked-out files where relevant?
A. Define $COMP_CVS_REMOTE. Setting this to anything will result in
the behaviour you would like.
Q. When I'm running a ./configure script and completion returns a list
of long options to me, some of these take a parameter,
e.g. --this-option=DESCRIPTION.
Running ./configure --help lists these descriptions, but everything
after the '=' is stripped when returning completions, so I don't
know what kind of data is expected as a given option's parameter.
Is there a way of getting ./configure completion to return the
entire option string, so that I can see what kind of data is
required and then simply delete the descriptive text and add my own
data?
A. Define $COMP_CONFIGURE_HINTS. Setting this to anything will result
in the behaviour you would like.
Q. When doing tar completion on a file within a tar file like this:
tar tzvf foo.tar.gz <Tab>
the pathnames contained in the tar file are not displayed
correctly. The slashes are removed and everything looks like it's
in a single directory. Why is this?
A. It's a choice we had to make. bash's programmable completion is
limited in how it handles the list of possible completions it
returns.
Because the paths returned from within the tar file are likely not
existing paths on the file system, '-o dirnames' must be passed to
the complete built-in to make it treat them as such. However, then
bash will append a space when completing on directories during
pathname completion to the tar files themselves.
It's more important to have proper completion of paths to tar files
than it is to have completion for their contents, so this sacrifice
was made and '-o filenames' is used with complete instead.
If you would rather have correct path completion for tar file
contents, define $COMP_TAR_INTERNAL_PATHS *before* sourcing
bash_completion.
Q. When completing on a symlink to a directory, bash does not append
the trailing / and I have to hit <Tab> again. I don't like this.
A. This has nothing to do with bash_completion. It's the default for
completing symlinks to directories since bash 2.05a, and was added
because sometimes you want to operate on the symlink itself, rather
than what it points to.
You can get the pre-2.05a behaviour back by putting
'set mark-symlinked-directories on' in your /etc/inputrc or ~/.inputrc
file.
Q. Completion goes awry when I try to complete on something that contains
a colon.
A. This is actually a 'feature' of bash. bash recognises a colon as
starting a new completion token, which is often what you want when
completing something like a PATH variable:
$ export PATH=/bin:/sbin:/usr<Tab>
Without the special treatment of the colon, the above wouldn't work
without programmable completion, so it has long been a feature of
the shell.
Unfortunately, you don't want the colon to be treated as a special
case when doing something like:
$ man File::B<Tab>
Here, the colons make bash think that it's completing the a new
token that begins with 'B'.
Unfortunately, there's no way to turn this off. The only thing you
can do is escape the colons with a backslash.
Q. Why is rpm completion so slow with -q?
A. Probably because the database is being queried every time and this uses a
lot of memory.
You can make this faster by pregenerating the list of installed packages on
the system. Make sure you have a readable file called /var/log/rpmpkgs.
It's generated by /etc/cron.daily/rpm on modern Red Hat and Mandrake
Linux systems.
If you don't have such a cron job, make one:
#!/bin/sh
rpm -qa --qf '%{name}-%{version}-%{release}.%{arch}.rpm\n' 2>&1 \
| sort > /var/log/rpmpkgs
rpm completion will use this flat text file instead of the RPM database,
unless it detects that the database has changed since the file was created,
in which case it will still use the database to ensure accuracy.
Q. bash-completion interferes with my command_not_found_handler function!
A. If your command_not_found_handler function is not intended to address
(possibly missing) commands invoked during bash programmable completion
functions, you can take that into account in your function for example by
testing if the $COMP_* variables are set and taking appropriate bypass or
other action.
Q. Can tab completion be made even easier?
A. The readline(3) library offers a few settings that can make tab
completion easier (or at least different) to use.
For example, try putting the following in either /etc/inputrc or
~/.inputrc:
set show-all-if-ambiguous on
This will allow single tab completion as opposed to requiring a
double tab. This makes things much more pleasant, in our opinion.
set visible-stats on
This will suffix each returned file completion with a character
denoting its type, in a similar way to ls(1) with -F or --classify.
set page-completions off
This turns off the use of the internal pager when returning long
completion lists.
Q. Is bash the be-all-and-end-all of completion as far as shells go?
A. Absolutely not. zsh has an extremely sophisticated completion system
that offers many features absent from the bash implementation. Its
users often cannot resist pointing this out. More information can
be found at:
http://www.zsh.org/
CONTRIBUTING
------------
Contributions to the bash completion project are more than
welcome. Fixes, clean-ups and improvements of existing code are much
appreciated, as are completion functions for new commands.
If you wish to contribute code, please bare the following coding
guidelines in mind:
- Do not use Perl, Ruby, Python etc. to do text processing unless the
command for which you are writing the completion code implies the
presence of one of those languages.
For example, if you were writing completion code for perldoc(1), the
use of Perl to achieve your goal would be acceptable. irb(1)
completion would similarly make the use of Ruby acceptable.
Even so, please consider alternatives to these large and slow to
start interpreters. Use lightweight programs such as grep(1), awk(1)
and sed(1).
- Use the full power of bash >= 4.1. We no longer support earlier bash
versions, so you may as well use all the features of that version of
bash to optimise your code. However, be careful when using features
added since bash 4.1, since not everyone will be able to use them.
For example, extended globs often enable you to avoid the use of
external programs, which are expensive to fork and execute, so do
make full use of those:
?(pattern-list) - match zero or one occurrences of patterns
*(pattern-list) - match zero or more occurrences of patterns
+(pattern-list) - match one or more occurrences of patterns
@(pattern-list) - match exactly one of the given patterns
!(pattern-list) - match anything except one of the given patterns
- Following on from the last point, be sparing with the use of
external processes whenever you can. Completion functions need to be
fast, so sacrificing some code legibility for speed is acceptable.
For example, judicious use of sed(1) can save you from having to
call grep(1) and pipe the output to cut(1), which saves a fork(2)
and exec(3).
Sometimes you don't even need sed(1) or other external programs at
all, though. Use of constructs such as ${parameter#word},
${parameter%word} and ${parameter/pattern/string} can provide you a
lot of power without having to leave the shell.
For example, if $foo contains the path to an executable, ${foo##*/}
will give you the basename of the program, without having to call
basename(1). Similarly, ${foo%/*} will give you the dirname, without
having to call dirname(1).
As another example,
bar=$( echo $foo | sed -e 's/bar/baz/g' )
can be replaced by:
bar=${foo//bar/baz}
These forms of parameter substitutions can also be used on arrays,
which makes them very powerful (if a little slow).
- Prefer "compgen -W '...' -- $cur" over embedding $cur in external
command arguments (often e.g. sed, grep etc) unless there's a good
reason to embed it. Embedding user input in command lines can
result in syntax errors and other undesired behavior, or messy
quoting requirements when the input contains unusual characters.
Good reasons for embedding include functionality (if the thing
does not sanely work otherwise) or performance (if it makes a big
difference in speed), but all embedding cases should be documented
with rationale in comments in the code.
- When completing available options, offer only the most descriptive
ones as completion results if there are multiple options that do the
same thing. Usually this means that long options should be preferred
over the corresponding short ones. This way the user is more likely
to find what she's looking for and there's not too much noise to
choose from, and there are less situations where user choice would be
needed in the first place. Note that this concerns only display of
available completions; argument processing/completion for options that
take an argument should be made to work with all known variants for
the functionality at hand. For example if -s, -S, and --something do
the same thing and require an argument, offer only --something as a
completion when completing option names starting with a dash, but do
implement required argument processing for all -s, -S, and --something.
Note that GNU versions of various standard commands tend to have long
options while other userland implementations of the same commands may
not have them, and it would be good to have the completions work for
as many userlands as possible so things aren't always that simple.
- Do not write to the file-system under any circumstances. This can
create race conditions, is inefficient, violates the principle of
least surprise and lacks robustness.
- Send small, incremental diffs that do one thing. Don't cram unrelated
changes into a single diff.
- Generate patches preferably against the git repository, with "git
format-patch origin/master" (assuming the diff was against the
origin/master branch), and send them preferably with "git
send-email". If you don't have git available or can't access the
repository for some reason, generate patches as unified diffs
('diff -u').
- If your code was written for a particular platform, try to make it
portable to other platforms, so that everyone may enjoy it. If your
code works only with the version of a binary on a particular
platform, ensure that it will not be loaded on other platforms that
have a command with the same name.
In particular, do not use GNU extensions to commands like sed and
awk if you can write your code another way. If you really, REALLY must
use them, do so if there's no other sane way to do what you're doing.
The "Shell and Utilities" volume of the POSIX specification is a good
starting reference for portable use of various utilities, see
http://www.opengroup.org/onlinepubs/9699919799/
- Read the existing source code for examples of how to solve
particular problems. Read the bash man page for details of all the
programming tools available to you within the shell.
- Please test your code thoroughly before sending it to us. We don't
have access to all the commands for which we are sent completion
functions, so we are unable to test them all personally. If your code
is accepted into the distribution, a lot of people will try it out,
so try to do a thorough job of eradicating all the bugs before you
send it to us.
- File bugs, enhancement requests (preferably with patches attached) at
the project tracker at https://alioth.debian.org/projects/bash-completion/
Sending them to the developers list usually works too, but bits are more
likely to fall through the cracks that way compared to the tracker.
- Use printf(1) instead of echo(1) for portability reasons, and be sure to
invoke commands that are often found aliased (such as ls or grep etc)
using the "command" (or "builtin") command as appropriate.
--
bash-completion developers
bash-completion-devel@lists.alioth.debian.org
00abd48e5b