/
githubmirror
/
bash-completion
Обзор
Документация
Войти
/
githubmirror
/
bash-completion
Код
Запросы
0
Пакеты
0
Релизы
0
Аналитика
Безопасность
1.1
README
496 строк
19 KB
Ville Skyttä
Add note about compgen -- $cur vs embedding $cur in external command arguments.
14 апр 2009, 22:38
14 апр 2009, 22:38
80db141
Код
Авторство
О чём код?
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. You 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 >= 2.04, 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. Here's another 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.gnu.org/gnu/bash/bash-2.05b-patches/bash205b-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. 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 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 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. - 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