diff --git a/README.md b/README.md index fcd966490fb..b163bae68c7 100644 --- a/README.md +++ b/README.md @@ -176,18 +176,22 @@ A. [ Disclaimer: Here, how to make the completion code visible to 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 + - The recommended directory is ``, 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 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 + completions for more than one command. The completion filename for command + `foo` in this directory should be `foo.bash`. Unsuffixed `foo` also + works, but it is deprecated in >= 2.18. + - Helper scripts used by completions may be placed in the directory + ``, which can be retrieved with `pkg-config + --variable=helpersdir bash-completion`. The completion files in + `` can reference the helper script `/` + as `${BASH_SOURCE[0]%/*}/../helpers/`. + - The other directory, which is only present for backwards compatibility and + is not recommended to use, is `` (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 diff --git a/bash_completion b/bash_completion index 9b8c2138fc0..2ba3250f58b 100644 --- a/bash_completion +++ b/bash_completion @@ -3506,14 +3506,12 @@ _comp_load() shift local -a source_args=("$@") - local i prefix - for prefix in "" _; do # Regular from all dirs first, then fallbacks - for i in "${!dirs[@]}"; do - dir=${dirs[i]}/completions - [[ -d $dir ]] || continue - for compfile in "$prefix$cmdname" "$prefix$cmdname.bash"; do - _comp_load__visit_file "$dir/$compfile" && return 0 - done + local i + for i in "${!dirs[@]}"; do + dir=${dirs[i]}/completions + [[ -d $dir ]] || continue + for compfile in "$cmdname.bash" "$cmdname"; do + _comp_load__visit_file "$dir/$compfile" && return 0 done done _comp_load__visit_file "$_comp__base_directory/completions-core/$cmdname.bash" && return 0 diff --git a/completions-core/Makefile.am b/completions-core/Makefile.am index 0d8e46036b9..f0f90c26ff6 100644 --- a/completions-core/Makefile.am +++ b/completions-core/Makefile.am @@ -169,7 +169,6 @@ cross_platform = 2to3.bash \ inject.bash \ inotifywait.bash \ installpkg.bash \ - interdiff.bash \ invoke-rc.d.bash \ ip.bash \ ipcalc.bash \ diff --git a/completions-fallback/Makefile.am b/completions-fallback/Makefile.am index 855c8ebd6f0..e908aeb79c2 100644 --- a/completions-fallback/Makefile.am +++ b/completions-fallback/Makefile.am @@ -17,6 +17,7 @@ cross_platform = adb.bash \ hexdump.bash \ hwclock.bash \ insmod.bash \ + interdiff.bash \ ionice.bash \ jj.bash \ jungle.bash \ diff --git a/completions-core/interdiff.bash b/completions-fallback/interdiff.bash similarity index 88% rename from completions-core/interdiff.bash rename to completions-fallback/interdiff.bash index 6f56e33aee4..3dc9211561d 100644 --- a/completions-core/interdiff.bash +++ b/completions-fallback/interdiff.bash @@ -1,5 +1,8 @@ # interdiff(1) completion -*- shell-script -*- +# Use of this file is deprecated. Upstream completion is available in +# patchutil >= 0.4.3, use that instead. + _comp_cmd_interdiff() { local cur prev words cword was_split comp_args diff --git a/completions/Makefile.am b/completions/Makefile.am index 76df678a109..bdafd910b34 100644 --- a/completions/Makefile.am +++ b/completions/Makefile.am @@ -1,7 +1,11 @@ # We include all the files in the tarball +scriptfiles = + bashcompdir = $(datadir)/$(PACKAGE)/completions -bashcomp_DATA = +bashcomp_DATA = README.md $(scriptfiles) + +EXTRA_DIST = $(bashcomp_DATA) symlinks: $(DATA) .PHONY: symlinks @@ -16,14 +20,8 @@ install-data-hook: symlinks check-local: REPLY=0; \ - for file in $(bashcomp_DATA); do \ + for file in $(scriptfiles); do \ $${bashcomp_bash:-$${BASH:-bash}} \ -O extglob -n $(srcdir)/$$file || REPLY=$$?; \ done; \ exit $$REPLY - -install-data-local: - $(MKDIR_P) $(DESTDIR)$(datadir)/bash-completion/$(subdir) - -uninstall-local: - -rmdir $(DESTDIR)$(datadir)/bash-completion/$(subdir) diff --git a/completions/README.md b/completions/README.md new file mode 100644 index 00000000000..27b95c5dfa2 --- /dev/null +++ b/completions/README.md @@ -0,0 +1,24 @@ +# Third-party completions directory - bash-completion + +This directory `completions` is the place to put **third-party completion +files** that are loaded by +[bash-completion](https://github.com/scop/bash-completion) on demand. + +> [!NOTE] +> +> The core `bash-completion` framework (<= 2.17) has provided also *completion +> files bundled with the bash-completion framework itself* in this directory, +> but we separated those files into `completions-core` and +> `completions-fallback`. However, external completion provider should +> continue to install their completion files in `completions`. The new +> directories `completions-core` and `completions-fallback` are internal +> directories intended to be used by the core `bash-completion`. + +The programmable completion for the command `` is supposed to be provided +as the file `completions/.bash`. The implementation examples are found in +`completions-core`, which uses the latest bash-completion API (v3). If you +want to make the completion file to work also with an older version of +`bash-completion`, you need to use the previous API of v2, which is contiuned +to be supported. For examples with API v2, please reference the completion +files in `completions` of +[bash-completion-2.11](https://github.com/scop/bash-completion/releases/tag/2.11). diff --git a/helpers/Makefile.am b/helpers/Makefile.am index bc049a1e299..f7e1b4582a4 100644 --- a/helpers/Makefile.am +++ b/helpers/Makefile.am @@ -1,10 +1,4 @@ helpersdir = $(datadir)/$(PACKAGE)/helpers -helpers_DATA = +helpers_DATA = README.md EXTRA_DIST = $(helpers_DATA) - -install-data-local: - $(MKDIR_P) $(DESTDIR)$(datadir)/bash-completion/$(subdir) - -uninstall-local: - -rmdir $(DESTDIR)$(datadir)/bash-completion/$(subdir) diff --git a/helpers/README.md b/helpers/README.md new file mode 100644 index 00000000000..420dd4a6f47 --- /dev/null +++ b/helpers/README.md @@ -0,0 +1,17 @@ +# Third-party helpers directory - bash-completion + +This directory `helpers` is the place to put **third-party helper scripts** +that are used by third-party completion files in the `completions` directory, +written for [bash-completion](https://github.com/scop/bash-completion). + +> [!NOTE] +> +> The core `bash-completion` framework (<= 2.17) has provided also *helper +> scripts included in the bash-completion framework itself* in this directory, +> but we separated those files into `helpers-core`. However, external +> completion provider should continue to install their helper scripts in +> `helpers`. The new directory `helpers-core` is an internal directory +> intended to be used by the core `bash-completion`. + +The helper script may be referenced by a completion script in `completions` +with `${BASH_COMPLETION[0]%/*}/../helpers/`.