1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
# bash-completion for Emacs [](https://github.com/szermatt/emacs-bash-completion/actions) [](https://melpa.org/#/bash-completion) [](https://stable.melpa.org/#/bash-completion)
bash-completion.el defines dynamic completion hooks for shell-mode
and shell-command prompts that is based on bash completion.
Bash completion for Emacs:
- is aware of bash builtins, aliases and functions
- does file expansion inside of colon-separated variables
and after redirections (> or <)
- escapes special characters when expanding file names
- is configurable through programmable bash completion
- works on remote shells, through TRAMP.
However, bash-completion.el only works with bash. If you run
other shells or other interactive programs that support completion,
bash-completion will not be able to help.
A more powerful alternative to bash-completion.el is [MisTTY],
as it works with all shells and most interactive programs that support
completion. On the other hand, MisTTY cannot integrate with Emacs
completion and is not able to provide completion in shell-command
prompts nor in eshell mode.
> [!NOTE]
> While I'm still maintaining bash-completion.el, I've switched
> to [MisTTY] for day-to-day operation, so that package is more
> likely to receive updates. -- szermatt
[MisTTY]: http://github.com/szermatt/mistty
## INSTALLATION
Copy bash-completion.el into a directory that's on Emacs load-path.
You can do that manually, or by installing it from
[MELPA](https://melpa.org/#/getting-started).
### Shell completion
To enable bash completion in shell buffers as well as in command
prompts, such as the prompt started by `compile`, add the hook
`bash-completion-dynamic-complete` to
`shell-dynamic-complete-functions`.
For example:
```elisp
(autoload 'bash-completion-dynamic-complete
"bash-completion"
"BASH completion hook")
(add-hook 'shell-dynamic-complete-functions
'bash-completion-dynamic-complete)
```
or simpler, but forces you to load bash-completion at startup:
```elisp
(require 'bash-completion)
(bash-completion-setup)
```
After that reload your .emacs (`M-x eval-buffer`) or restart.
When called from a bash shell buffer,
`bash-completion-dynamic-complete` communicates with the current shell
to reproduce, as closely as possible the normal bash auto-completion,
available on full terminals.
When called from non-shell buffers, such as the prompt of M-x compile,
`bash-completion-dynamic-complete` creates a separate bash process
just for doing completion. Such processes have the environment
variable `EMACS_BASH_COMPLETE` set to `t`, to help distinguish them
from normal shell processes.
### Completion at point
You can also use bash completion as an additional completion function
in any buffer that contains bash commands. To do that, add
`bash-completion-capf-nonexclusive` to the buffer-local
`completion-at-point-functions`. For example, you can setup bash
completion in `eshell-mode` by invoking
```elisp
(add-hook 'eshell-mode-hook
(lambda ()
(add-hook 'completion-at-point-functions
'bash-completion-capf-nonexclusive nil t)))
```
There is also a lower-level function
`bash-completion-dynamic-complete-nocomint` which allows you to
construct your own `completion-at-point` function.
```elisp
(bash-completion-dynamic-complete-nocomint COMP-START COMP-POS DYNAMIC-TABLE)
```
COMP-START is where the bash command starts --- it depends on the mode
of the calling buffer. In most cases, `line-beginning-position` works
because it uses `field` boundaries.
COMP-POS is usually the current position of the cursor.
When calling from `completion-at-point`, make sure to pass a non-nil
value to the DYNAMIC-TABLE argument so it returns a function instead
of a list of strings. This isn't just an optimization: returning a
function instead of a list tells Emacs it should avoids post-filtering
the results and possibly discarding useful completion from bash.
## TROUBLESHOOTING
If completion in a bash shell doesn't behave as you think it should, check
the following:
* Does bash behave differently when run outside of Emacs? If not, check
your shell configuration.
* Call `M-x bash-completion-debug` and look at the `output-buffer`
section. Does it match the expected set of completion? If yes,
it might be a display problem. Are you using a completion engine
other than the default, such as ivy or helm? Try turning it off to
confirm, then [file a bug](
https://github.com/szermatt/emacs-bash-completion/issues/new).
* If all else fails, [file a bug](
https://github.com/szermatt/emacs-bash-completion/issues/new). Please
include the output of `M-x bash-completion-debug`, the command you're
trying to use and the function or package providing completion for
that command and where to download it.
## CONTRIBUTING
To report bugs, features, please open an [issue](
https://github.com/szermatt/emacs-bash-completion/issues/new). To ask
questions or just for general comments, add a new [discussion](
https://github.com/szermatt/emacs-bash-completion/discussions). To
contribute code or documentation, please open a [pull request](
https://github.com/szermatt/emacs-bash-completion/pulls).
See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
## COMPATIBILITY
bash-completion.el is known to work with Bash 4.2 and later and Bash
5, on Emacs, starting with version 25.3, under Linux and OSX.
|
