bash-completion/README

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
if [ -f /etc/bash_completion ]; then
  . /etc/bash_completion
fi

(if you happen to have *only* bash >= 3, see further if not)

If you don't have the package readily available for your distribution, 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, as
explained above.

A more elaborate way that takes care of not loading on old, unsupported
bash versions as well as some other conditions is included in the bash
completion package as bash_completion.sh.  If your system has the
/etc/profile.d directory and loads all files from it automatically,
you may place the file in it.  If not, place the file somewhere on your
system and source it from /etc/bashrc or ~/.bashrc, or copy its contents
to one of those files.

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

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

V.

After upgrading to bash 3.1, you may notice that completing on certain
commands now fails with a message something like this:

   sed: -e expression #1, char 20: unterminated `s' command

The reason for this is that bash 3.1 contains the following,
innocent-looking bug fix (from bash's CHANGES file):

  t.  Fixed a bug that caused the expanded value of a $'...' string
      to be incorrectly re-quoted if it occurred within a
      double-quoted ${...} parameter expansion.

Unfortunately, this also had the side effect of causing single quotes
to be stripped from $'...' strings inside double-quoted command
substitutions. Confused?

Efforts have been made to work around this issue in the bash
completion code as of the 20060301 release. All previous versions are
vulnerable to the problem. However, it's possible that, even in the
20060301 release and later, affected code remains.

The issue has now been officially recognised as a regression in the
bash 3.1 release and is fixed by official patch 11. If you encounter
problems of this nature, please apply the patch below to your copy of
bash:

	ftp://ftp.gnu.org/gnu/bash/bash-3.1-patches/bash31-011


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 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 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. 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 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 >= 3. 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 3.0, since not everyone will be able to use them. Be
  ESPECIALLY careful of using features exclusive to 4.x, as many people
  are still using 3.x.

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

-- 
bash-completion developers
bash-completion-devel@lists.alioth.debian.org