diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 63 |
1 files changed, 27 insertions, 36 deletions
@@ -2,6 +2,13 @@ [](https://travis-ci.org/scop/bash-completion) +## Introduction + +bash-completion is a collection of command line command completions for the +[Bash shell](https://www.gnu.org/software/bash/), collection of helper +functions to assist in creating new completions, and set of facilities for +loading completions automatically on demand, as well as installing them. + ## Installation The easiest way to install this software is to use a package; refer to @@ -18,7 +25,7 @@ other file sourcing those). You can do this by simply using: . /usr/share/bash-completion/bash_completion ``` -(if you happen to have *only* bash >= 4.1 installed, see further if not) +(if you happen to have *only* bash >= 4.2 installed, see further if not) If you don't have the package readily available for your distribution, or you simply don't want to use one, you can install bash completion using the @@ -27,9 +34,9 @@ standard commands for GNU autotools packages: ```shell autoreconf -i # if not installing from prepared release tarball ./configure -make -make check # optional, requires python3 with pytest >= 3.6 and pexpect, dejagnu, and tcllib -make install # as root +make # GNU make required +make check # optional, requires python3 with pytest >= 3.6, pexpect +make install # as root ``` These commands install the completions and helpers, as well as a @@ -62,7 +69,6 @@ if [ -f /sw/etc/bash_completion ]; then fi ``` - ## Troubleshooting If you find that a given function is producing errors or does not work @@ -77,7 +83,6 @@ on before the debugged completion is attempted the first time. The easiest way to do this is to start a new shell session, and to turn tracing on in it before doing anything else there. - ## Known problems 1. There seems to be some issue with using the bash built-in `cd` within @@ -90,21 +95,6 @@ tracing on in it before doing anything else there. text utilities that they call (e.g. `grep`, `sed`, and `awk`). Your mileage may vary. -3. If you are seeing 'unbound variable' warnings from bash when - hitting <kbd><Tab></kbd>, 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. - - ## FAQ **Q. The bash completion code inhibits some commands from completing on @@ -136,7 +126,8 @@ A. Install a local completion of your own appropriately for the desired A. Put them in the `completions` subdir of `$BASH_COMPLETION_USER_DIR` (defaults to `$XDG_DATA_HOME/bash-completion` or `~/.local/share/bash-completion` - if `$XDG_DATA_HOME` is not set) to have them loaded on demand. + if `$XDG_DATA_HOME` is not set) to have them loaded automatically + on demand when the respective command is being completed. See also the next question's answer for considerations for these files' names, they apply here as well. Alternatively, you can write them directly in `~/.bash_completion` which is loaded eagerly by @@ -151,20 +142,20 @@ A. Install it in one of the directories pointed to by alternatives: - The recommended directory is `completionsdir`, which you can get with - `pkg-config --variable=completionsdir bash-completion`. From this - directory, completions are loaded on-demand based on invoked commands' names, - so be sure to name your completion file accordingly, and to include - (for example) symbolic links in case the file provides completions - for more than one command. + `pkg-config --variable=completionsdir bash-completion`. From this + directory, completions are automatically loaded on demand based on invoked + commands' names, so be sure to name your completion file accordingly, and + to include (for example) symbolic links in case the file provides + completions for more than one command. - The other directory (which only present for backwards compatibility) is `compatdir` (get it with - `pkg-config --variable=compatdir bash-completion`) from which files - are loaded when `bash_completion` is loaded. + `pkg-config --variable=compatdir bash-completion`) from which files + are loaded when `bash_completion` is loaded. For packages using GNU autotools the installation can be handled for example like this in `configure.ac`: - ``` + ```m4 PKG_CHECK_VAR(bashcompdir, [bash-completion], [completionsdir], , bashcompdir="${sysconfdir}/bash_completion.d") AC_SUBST(bashcompdir) @@ -180,7 +171,7 @@ A. Install it in one of the directories pointed to by For cmake we ship the `bash-completion-config.cmake` and `bash-completion-config-version.cmake` files. Example usage: - ``` + ```cmake find_package(bash-completion) if(BASH_COMPLETION_FOUND) message(STATUS @@ -221,7 +212,7 @@ A. Define `$COMP_CONFIGURE_HINTS`. Setting this to anything will **Q. When doing tar completion on a file within a tar file like this:** - ``` + ```shell tar tzvf foo.tar.gz <Tab> ``` @@ -327,21 +318,21 @@ A. The `readline(3)` library offers a few settings that can make tab For example, try putting the following in either `/etc/inputrc` or `~/.inputrc`: - ``` + ```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. - ``` + ```inputrc 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`. - ``` + ```inputrc set page-completions off ``` @@ -353,4 +344,4 @@ A. The `readline(3)` library offers a few settings that can make tab 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/ + be found at <https://www.zsh.org/>. |