diff options
Diffstat (limited to 'debian/bash_completion/README')
| -rw-r--r-- | debian/bash_completion/README | 448 |
1 files changed, 448 insertions, 0 deletions
diff --git a/debian/bash_completion/README b/debian/bash_completion/README new file mode 100644 index 0000000..93616af --- /dev/null +++ b/debian/bash_completion/README @@ -0,0 +1,448 @@ +$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> |