csonto/bash-completion
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

- add FAQ entry on colons starting a new completion token

Browse Source
This commit is contained in:
ianmacd 2002-12-17 08:53:18 +00:00
parent dc0b6fbcf8
commit 4dc02f42c7
1 changed files with 133 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

228
README
View File

@ -1,12 +1,12 @@
$Id: README,v 1.16 2002/12/05 05:26:28 ianmacd Exp $ $Id: README,v 1.17 2002/12/17 09:53:18 ianmacd Exp $
INSTALLATION INSTALLATION
------------ ------------
If you are installing the source file manually as opposed to using a packaging If you are installing the source file manually as opposed to using a
system such as dpkg or rpm, put it somewhere on your system and source it from packaging system such as dpkg or rpm, put it somewhere on your system
either /etc/bashrc or ~/.bashrc. and source it from either /etc/bashrc or ~/.bashrc.
Here's one possible way of doing that from /etc/bashrc: Here's one possible way of doing that from /etc/bashrc:
@ -18,48 +18,54 @@ if [ "$PS1" ] && [ $bmajor -eq 2 ] && [ $bminor '>' 04 ] \
fi fi
unset bash bmajor bminor unset bash bmajor bminor
This code checks that the version of bash that is parsing the code is later This code checks that the version of bash that is parsing the code is
than 2.04 and, if so, sources the bash completion code. 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 While this code may, at first, seem overly complex, the advantage of
is that it will also parse correctly when interpreted by bash 1.x. If you have using it is that it will also parse correctly when interpreted by bash
bash 1.x and bash 2.x users on your system, you must avoid using constructs 1.x. If you have bash 1.x and bash 2.x users on your system, you must
that were not valid under 1.x syntax. avoid using constructs that were not valid under 1.x syntax.
If you are putting the bash completion source file somewhere other than If you are putting the bash completion source file somewhere other
/etc/bash_completion, you should ensure that $BASH_COMPLETION is set to point than /etc/bash_completion, you should ensure that $BASH_COMPLETION is
to it before you source it. Your ~/.bashrc file is a good place to do this. set to point to it before you source it. Your ~/.bashrc file is a good
place to do this.
TROUBLESHOOTING TROUBLESHOOTING
--------------- ---------------
If you get errors about 'complete' or 'compgen' not accepting the -g flag, If you get errors about 'complete' or 'compgen' not accepting the -g
you are probably running bash 2.05 and should either apply the group completion flag, you are probably running bash 2.05 and should either apply the
patch, download a prepatched bash binary of 2.05, or upgrade to 2.05a or later. 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 If you find that some commands, such as 'cd /usr<Tab>', end with a
space instead of appending a /, you are probably running the base version of trailing space instead of appending a /, you are probably running the
bash 2.05, which suffers from a bug that causes the '-o filenames' option to base version of bash 2.05, which suffers from a bug that causes the
the complete built-in to be ignored. You can fix this by applying the following '-o filenames' option to the complete built-in to be ignored. You can
the following official patch from the bash maintainer: 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 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 If you get errors about 'complete' not accepting the -o flag, you are
running bash 2.04. In this case, you should upgrade to bash 2.05a or later. probably running bash 2.04. In this case, you should upgrade to bash
However, I have endeavoured to make the code detect this version of bash and 2.05a or later. However, I have endeavoured to make the code detect
work around this issue, so please inform me if you still encounter this error. 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: Copies of the patches and prepatched versions of bash are available
from:
http://www.caliban.org/bash/ http://www.caliban.org/bash/
If you find that a given function is producing errors under certain If you find that a given function is producing errors under certain
circumstances when you attempt completion, try running 'set -v' or 'set -x' circumstances when you attempt completion, try running 'set -v' or
prior to attempting the completion again. This will produce useful debugging 'set -x' prior to attempting the completion again. This will produce
output that will aid me in fixing the problem if you are unable to do so useful debugging output that will aid me in fixing the problem if you
yourself. Turn off the trace output by running either 'set +v' or 'set +x'. are unable to do so yourself. Turn off the trace output by running
either 'set +v' or 'set +x'.
KNOWN PROBLEMS KNOWN PROBLEMS
@ -67,110 +73,142 @@ KNOWN PROBLEMS
I. I.
There seems to be some issue with using the bash built-in cd within Makefiles. There seems to be some issue with using the bash built-in cd within
When invoked as /bin/sh within Makefiles, bash seems to have a problem changing Makefiles. When invoked as /bin/sh within Makefiles, bash seems to
directory via the cd command. A work-around for this is to define have a problem changing directory via the cd command. A work-around
SHELL=/bin/bash within your Makefile. This is believed to be a bug in bash. for this is to define SHELL=/bin/bash within your Makefile. This is
believed to be a bug in bash.
II. II.
The have() function is used to conserve memory by only installing completion The have() function is used to conserve memory by only installing
functions for those programs that are actually present on your system. The completion functions for those programs that are actually present on
current method of determining whether or not a given binary is present is your system. The current method of determining whether or not a given
whether or not it is in your $PATH. 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 This approach has the disadvantage that sudo completion will not be
perform sub-completion on, say, service, if /sbin is not in your path, which, able to perform sub-completion on, say, service, if /sbin is not in
as an unprivileged user, it typically isn't. 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 The work-around for this is to put all directories of binaries for
require completion into your $PATH variable prior to sourcing bash_completion. which you require completion into your $PATH variable prior to
sourcing bash_completion.
III. III.
Many of the completion functions assume GNU versions of the various text Many of the completion functions assume GNU versions of the various
utilities that they call (e.g. grep, sed and awk). Your mileage may vary. text utilities that they call (e.g. grep, sed and awk). Your mileage
may vary.
FAQ FAQ
--- ---
Q. How can I insert my own local completions without having to reinsert them Q. How can I insert my own local completions without having to
every time you issue a new release? reinsert them every time you issue a new release?
A. Put them in ~/.bash_completion, which is parsed at the end of the main A. Put them in ~/.bash_completion, which is parsed at the end of the
completion script. main completion script.
Q. I author/maintain package X and would like to maintain my own completion Q. I author/maintain package X and would like to maintain my own
code for this package. Where should I put it to be sure that interactive completion code for this package. Where should I put it to be sure
bash shells will find it and source it? that interactive bash shells will find it and source it?
Put it in the directory pointed to by $BASH_COMPLETION_DIR, which is defined Put it in the directory pointed to by $BASH_COMPLETION_DIR, which
at the beginning of the main completion script. Any scripts placed in this is defined at the beginning of the main completion script. Any
directory will be sourced by interactive bash shells. 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 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 repository. How can I have the cvs command complete on remotely
files where relevant? checked-out files where relevant?
A. Define $COMP_CVS_REMOTE. Setting this to anything will result in the A. Define $COMP_CVS_REMOTE. Setting this to anything will result in
behaviour you would like. the behaviour you would like.
Q. When I'm running a ./configure script and completion returns a list of Q. When I'm running a ./configure script and completion returns a list
long options to me, some of these take a parameter, of long options to me, some of these take a parameter,
e.g. --this-option=DESCRIPTION. e.g. --this-option=DESCRIPTION.
Running ./configure --help lists these descriptions, but everything after Running ./configure --help lists these descriptions, but everything
the '=' is stripped when returning completions, so I don't know what kind after the '=' is stripped when returning completions, so I don't
of data is expected as a given option's parameter. 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 Is there a way of getting ./configure completion to return the
option string, so that I can see what kind of data is required and then entire option string, so that I can see what kind of data is
simply delete the descriptive text and add my own data? 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 A. Define $COMP_CONFIGURE_HINTS. Setting this to anything will result
behaviour you would like. in the behaviour you would like.
Q. When doing tar completion on a file within a tar file like this: Q. When doing tar completion on a file within a tar file like this:
tar tzvf foo.tar.gz <Tab> tar tzvf foo.tar.gz <Tab>
the pathnames contained in the tar file are not displayed correctly. The the pathnames contained in the tar file are not displayed
slashes are removed and everything looks like it's in a single directory. correctly. The slashes are removed and everything looks like it's
Why is this? in a single directory. Why is this?
A. It's a choice I had to make. bash's programmable completion is limited in A. It's a choice I had to make. bash's programmable completion is
how it handles the list of possible completions it returns. 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 Because the paths returned from within the tar file are likely not
paths on the file system, '-o dirnames' must be passed to the complete existing paths on the file system, '-o dirnames' must be passed to
built-in to make it treat them as such. However, then bash will append a the complete built-in to make it treat them as such. However, then
space when completing on directories during pathname completion to the tar bash will append a space when completing on directories during
files themselves. pathname completion to the tar files themselves.
It's more important to have proper completion of paths to tar files than It's more important to have proper completion of paths to tar files
it is to have completion for their contents, so this sacrifice was made than it is to have completion for their contents, so this sacrifice
and '-o filenames' is used with complete instead. was made and '-o filenames' is used with complete instead.
If you would rather have correct path completion for tar file contents, If you would rather have correct path completion for tar file
define $COMP_TAR_INTERNAL_PATHS *before* sourcing bash_completion. contents, define $COMP_TAR_INTERNAL_PATHS *before* sourcing
bash_completion.
Q. When completing on a symlink to a directory, bash does not append the Q. When completing on a symlink to a directory, bash does not append
trailing / and I have to hit <Tab> again. I don't like this. 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 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 completing symlinks to directories in bash 2.05a, and was added
sometimes you want to operate on the symlink itself, rather than what it because sometimes you want to operate on the symlink itself, rather
points to. than what it points to.
In bash 2.05b and later, you can get the pre-2.05a behaviour back by In bash 2.05b and later, you can get the pre-2.05a behaviour back
putting 'set mark-symlinked-directories on' in your /etc/inputrc or by putting 'set mark-symlinked-directories on' in your /etc/inputrc
~/.inputrc file. or ~/.inputrc file.
Q. This code is rubbish/not bad/pretty good/the best thing since sliced bread. Q. Completion goes awry when I try to complete on something that contains
How can I show my appreciation? a colon.
A. If you're a registered Freshmeat user, take a moment to rate the project at: 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/ http://freshmeat.net/rate/19041/