$Id: README,v 1.17 2002/12/17 09:53:18 ianmacd Exp $
INSTALLATION
------------
If you are installing the source file manually as opposed to using a
packaging system such as dpkg or rpm, put it somewhere on your system
and source it from either /etc/bashrc or ~/.bashrc.
Here's one possible way of doing that from /etc/bashrc:
bash=${BASH_VERSION%.*}; bmajor=${bash%.*}; bminor=${bash#*.}
if [ "$PS1" ] && [ $bmajor -eq 2 ] && [ $bminor '>' 04 ] \
&& [ -f /etc/bash_completion ]; then # interactive shell
# Source completion code
. /etc/bash_completion
fi
unset bash bmajor bminor
This code checks that the version of bash that is parsing the code is
later than 2.04 and, if so, sources the bash completion code.
While this code may, at first, seem overly complex, the advantage of
using it is that it will also parse correctly when interpreted by bash
1.x. If you have bash 1.x and bash 2.x users on your system, you must
avoid using constructs that were not valid under 1.x syntax.
If you are putting the bash completion source file somewhere other
than /etc/bash_completion, you should ensure that $BASH_COMPLETION is
set to point to it before you source it. Your ~/.bashrc file is a good
place to do this.
TROUBLESHOOTING
---------------
If you get errors about 'complete' or 'compgen' not accepting the -g
flag, you are probably running bash 2.05 and should either apply the
group completion patch, download a prepatched bash binary of 2.05, or
upgrade to 2.05a or later.
If you find that some commands, such as 'cd /usr<Tab>', end with a
trailing space instead of appending a /, you are probably running the
base version of bash 2.05, which suffers from a bug that causes the
'-o filenames' option to the complete built-in to be ignored. You can
fix this by applying the following the following official patch from
the bash maintainer:
ftp://ftp.cwru.edu/pub/bash/bash-2.05-patches/bash205-006
If you get errors about 'complete' not accepting the -o flag, you are
probably running bash 2.04. In this case, you should upgrade to bash
2.05a or later. However, I have endeavoured to make the code detect
this version of bash and work around this issue, so please inform me
if you still encounter this error.
Copies of the patches and prepatched versions of bash are available
from:
http://www.caliban.org/bash/
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 me 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.
The have() function is used to conserve memory by only installing
completion functions for those programs that are actually present on
your system. The current method of determining whether or not a given
binary is present is whether or not it is in your $PATH.
This approach has the disadvantage that sudo completion will not be
able to perform sub-completion on, say, service, if /sbin is not in
your path, which, as an unprivileged user, it typically isn't.
The work-around for this is to put all directories of binaries for
which you require completion into your $PATH variable prior to
sourcing bash_completion.
III.
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
---
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.
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?
Put it in the directory pointed to by $BASH_COMPLETION_DIR, which
is defined at the beginning of the main completion script. Any
scripts placed in this directory will be sourced by interactive
bash shells.
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 I 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 in bash 2.05a, and was added
because sometimes you want to operate on the symlink itself, rather
than what it points to.
In bash 2.05b and later, 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. This code is rubbish/not bad/pretty good/the best thing since
sliced bread. How can I show my appreciation?
A. If you're a registered Freshmeat user, take a moment to rate the
project at:
http://freshmeat.net/rate/19041/
Of course, writing to me and letting me know how you feel also works.
Patches and new completion routines are most welcome, too.
Q. How can I stay abreast of new releases?
A. If you're a registered Freshmeat user, you can subscribe to new release
announcements at:
http://freshmeat.net/subscribe/19041/
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 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 2.x. Programmable completion has only
been available since bash 2.04, 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 2.04, since not everyone
will be able to use them.
For example, here strings (<<<) were not added until 2.05b, so don't
use them for the time being. On the other hand, extended globs often
enable you to avoid the use of external programs, which are
expensive to fork and execute, so do use those:
?(pattern-list) - match zero or one occurences of patterns
*(pattern-list) - match zero or more occurences of patterns
+(pattern-list) - match one or more occurences 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, try to save 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, 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.
- 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 your patches as unified diffs. You can make this with 'diff -u'.
- Send small, incremental diffs that affect a single function. Don't
cram massive, unrelated patches into a single diff.
- 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 have the choice. If you really must use them, however, do
feel free to do so.
- 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 me. I don't
have access to all the commands for which I am sent completion
functions, so I am unable to test them 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 me.
--
Ian Macdonald <ian@caliban.org>
