diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 174 |
1 files changed, 91 insertions, 83 deletions
@@ -1,6 +1,6 @@ # bash-completion -[](https://travis-ci.org/scop/bash-completion) +[](https://github.com/scop/bash-completion/actions/workflows/ci.yaml) ## Introduction @@ -17,7 +17,8 @@ list of operating system distributions, package names, and available versions. 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: +other file sourcing those). If you have _only_ bash >= 4.2 installed, you can +do this by simply using: ```shell # Use bash-completion, if available @@ -25,26 +26,28 @@ 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.2 installed, see further if not) +If you have older bash versions in use, their loading of `bash_completion` +should be prevented. See further for more info. 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 standard commands for GNU autotools packages: ```shell -autoreconf -i # if not installing from prepared release tarball +autoreconf -i # if not installing from prepared release tarball ./configure -make # GNU make required -make check # optional, requires python3 with pytest >= 3.6, pexpect -make install # as root +make # GNU make required +make check # optional +make install # as root +make installcheck # optional, requires python3 with pytest >= 3.6, pexpect ``` These commands install the completions and helpers, as well as a `profile.d` script that loads `bash_completion` where appropriate. If your system does not use the `profile.d` directory (usually below -`/etc`) mechanism—i.e. does not automatically source shell scripts in -it—you can source the `$sysconfdir/profile.d/bash_completion.sh` +`/etc`) mechanism (i.e., does not automatically source shell scripts in +it), you can source the `$sysconfdir/profile.d/bash_completion.sh` script in `/etc/bashrc` or `~/.bashrc`. The `profile.d` script provides a configuration file hook that can be @@ -73,10 +76,15 @@ fi If you find that a given function is producing errors or does not work as it should under certain circumstances when you attempt completion, -try running `set -v` or `set -x` prior to attempting the completion +try running `set -x` or `set -v` 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`. +trace output by running either `set +x` or `set +v`. + +If you are filing an issue, please attach the generated debugging output +in `set -x` mode copy-pasted to a separate, attached file in the report. +Before doing so, be sure to review the output for anything you may not want +to share in public, and redact as appropriate. To debug dynamic loading of a completion, tracing needs to be turned on before the debugged completion is attempted the first time. The @@ -85,13 +93,7 @@ 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 - Makefiles. When invoked as `/bin/sh` within `Makefile`s, 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. - -2. Many of the completion functions assume GNU versions of the various +1. 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. @@ -111,11 +113,12 @@ A. No. Use `M-/` to (in the words of the bash man page) attempt file A. Install a local completion of your own appropriately for the desired command, and it will take precedence over the one shipped by us. See the - next answer for details where to install it, if you are doing it on per - user basis. If you want to do it system wide, you can install eagerly - loaded files in `compatdir` (see a couple of questions further down for - more info) and install a completion for the commands to override our - completion for in them. + next answer for details where to install it, if you are doing it on per user + basis. If you want to do it system wide, you can install eagerly loaded + files in `compatdir` (see a couple of questions further down for more + info. To get the path of `compatdir` for the current system, the output of + `pkg-config bash-completion --variable compatdir` can be used) and install a + completion for the commands to override our completion for in them. If you want to use bash's default completion instead of one of ours, something like this should work (where `$cmd` is the command to override @@ -137,20 +140,28 @@ A. Put them in the `completions` subdir of `$BASH_COMPLETION_USER_DIR` completion code for this package. Where should I put it to be sure that interactive bash shells will find it and source it?** -A. Install it in one of the directories pointed to by - bash-completion's `pkgconfig` file variables. There are two - alternatives: +A. [ Disclaimer: Here, how to make the completion code visible to + bash-completion is explained. We do not require always making the + completion code visible to bash-completion. In what condition the + completion code is installed should be determined at the author/maintainers' + own discretion. ] + + Install it in one of the directories pointed to by bash-completion's + `pkgconfig` file variables. There are two alternatives: - The recommended directory is `completionsdir`, which you can get with `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. + completions for more than one command. The completion filename for + command `foo` in this directory should be either `foo`, or `foo.bash`. + (Underscore prefixed `_foo` works too, but is reserved for + bash-completion internal use as a deprecation/fallback marker.) + - The other directory which is only present for backwards compatibility, + its usage is no longer recommended, is `compatdir` (get it with + `pkg-config --variable=compatdir bash-completion`). From this + directory, files are loaded eagerly when `bash_completion` is loaded. For packages using GNU autotools the installation can be handled for example like this in `configure.ac`: @@ -165,7 +176,7 @@ A. Install it in one of the directories pointed to by ```makefile bashcompdir = @bashcompdir@ - dist_bashcomp_DATA = # completion files go here + dist_bashcomp_DATA = your-completion-file # completion files go here ``` For cmake we ship the `bash-completion-config.cmake` and @@ -186,57 +197,27 @@ A. Install it in one of the directories pointed to by ${BASH_COMPLETION_COMPLETIONSDIR}) ``` -**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. + In bash-completion >= 2.12, we search the data directory of + `bash-completion` under the installation prefix where the target command is + installed. When one can assume that the version of the target + bash-completion is 2.12 or higher, the completion script can actually be + installed to `$PREFIX/share/bash-completion/completions/` under the same + installation prefix as the target program installed under `$PREFIX/bin/` or + `$PREFIX/sbin/`. For the detailed search order, see also "Q. What is the + search order for the completion file of each target command?" below. -**Q. When doing tar completion on a file within a tar file like this:** + Example for `Makefile.am`: - ```shell - tar tzvf foo.tar.gz <Tab> + ```makefile + bashcompdir = $(datarootdir)/bash-completion/completions + dist_bashcomp_DATA = your-completion-file ``` - **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. + Example for `CMakeLists.txt`: - 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`. + ```cmake + install(FILES your-completion-file DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/bash-completion/completions") + ``` **Q. When completing on a symlink to a directory, bash does not append the trailing `/` and I have to hit <kbd><Tab></kbd> again. @@ -286,7 +267,7 @@ A. Probably because the database is being queried every time and this uses a 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 + `/var/log/rpmpkgs`. It's generated by `/etc/cron.daily/rpm` on some Red Hat and Mandrake and derivative Linux systems. If you don't have such a cron job, make one: @@ -302,13 +283,15 @@ A. Probably because the database is being queried every time and this uses a 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. bash-completion interferes with my `command_not_found_handler` function!** +**Q. bash-completion interferes with my `command_not_found_handle` function + (or the other way around)!** -A. If your `command_not_found_handler` function is not intended to +A. If your `command_not_found_handle` function is not intended to address (possibly missing) commands invoked during bash programmable completion functions, you can account for this - by, for example, testing if the `$COMP_`\* variables are set and - taking appropriate bypass or other action. + in the function by, for example, testing if the `$COMP_LINE` + variable is set and taking appropriate action, typically returning + early and silently with success. **Q. Can tab completion be made even easier?** @@ -345,3 +328,28 @@ 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 <https://www.zsh.org/>. + +**Q. What is the search order for the completion file of each target command?** + +A. The completion files of commands are looked up by the shell function + `__load_completion`. Here, the search order in bash-completion >= 2.12 is + explained. + + 1. `BASH_COMPLETION_USER_DIR`. The subdirectory `completions` of each paths + in `BASH_COMPLETION_USER_DIR` separated by colons is considered for a + completion directory. + 2. The location of the main `bash_completion` file. The subdirectory + `completions` in the same directory as `bash_completion` is considered. + 3. The location of the target command. When the real location of the command + is in the directory `<prefix>/bin` or `<prefix>/sbin`, the directory + `<prefix>/share/bash-completion/completions` is considered. + 4. `XDG_DATA_DIRS` (or the system directories `/usr/local/share:/usr/share` + if empty). The subdirectory `bash-completion/completions` of each paths + in `XDG_DATA_DIRS` separated by colons is considered. + + The completion files of the name `<cmd>` or `<cmd>.bash`, where `<cmd>` is + the name of the target command, are searched in the above completion + directories in order. The file that is found first is used. When no + completion file is found in any completion directories in this process, the + completion files of the name `_<cmd>` is next searched in the completion + directories in order. |