$Id: README,v 1.26 2006/02/25 14:41:11 ianmacd Exp $


INSTALLATION
------------

The easiest way to install this software is to use a package, such as
the RPM that I maintain for Red Hat Linux, the .deb package for
Debian/GNU Linux or Ubuntu, etc.

If that's not an option or you simply don't want to do this, put the
bash_completion file somewhere on your system and source it from either
/etc/bashrc or ~/.bashrc.

Here's one possible way of doing that from /etc/bashrc:

# Check for interactive shell.
if [ -n "$PS1" ]; then
  if [ $bmajor -eq 2 -a $bminor '>' 04 ] || [ $bmajor -gt 2 ]; then
    if [ -r /etc/bash_completion ]; then
      # Source completion code.
      . /etc/bash_completion
    fi
  fi
fi
unset bash bminor bmajor

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/3.x users on your system, you
must avoid using constructs that were not valid under 1.x syntax.

If your system has an /etc/profile.d directory, you might instead want
to add a script called bash_completion.sh to that directory. Add the
above code, preceded by the following:

# Check for bash.
[ -z "$BASH_VERSION" ] && return

In this case, all *.sh scripts in /etc/profile.d are sourced from
/etc/bashrc by Bourne-like shells, so you need the extra check for bash
in order to avoid sourcing the rest of the script if a shell other than
bash is running.

For your convenience, a sample bash_completion.sh file is included in
the package.

If you're using MacOS X, /etc/bashrc is apparently not sourced at all.
In that case, you should 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

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 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 can be found along a certain
path of directories. The path that is currently searched is:

	$PATH:/sbin:/usr/sbin:/usr/local/sbin

where $PATH is your user path at the time the bash completion file is
sourced.

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.

IV.

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 I 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 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?

   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. Usually, this is /etc/bash_completion.d.

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. Where did urpmi completion go?

A. Guillaume Rousse <rousse@ccr.jussieu.fr> now maintains it separately as
   part of the urpmi RPM package.

   CVS: http://cvs.mandrakesoft.com/cgi-bin/cvsweb.cgi/soft/urpmi/
   Web: http://urpmi.org/

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. 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 my 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. 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/

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 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. Be ESPECIALLY careful of using features
  exclusive to 3.x, as many people are still using 2.x.

  For example, here strings (<<<) were not added until 2.05b, so don't
  use them for the time being.

  Similarly, 3.0 added the use of the regex operator '=~', commonly
  found in Perl and Ruby. Whilst this is very useful, it's not yet
  safe to assume its ubiquity.
  
  On the other hand, extended globs were added in bash 2.02 and 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 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, 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).

- 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 these 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 can write your code another way. 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 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 me.
  
-- 
Ian Macdonald <ian@caliban.org>