bash-completion for Emacs

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.

A simpler and more complete alternative to bash-completion.el is to run a bash shell in a buffer in term mode (

M-x ansi-term

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.

Shell completion

To enable bash completion in shell buffers as well as in command prompts, such as the prompt started by

compile

bash-completion-dynamic-complete

shell-dynamic-complete-functions

For example:

        (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:

        (require 'bash-completion)
        (bash-completion-setup)

After that reload your .emacs (

M-x eval-buffer

When called from a bash shell buffer,

bash-completion-dynamic-complete

When called from non-shell buffers, such as the prompt of M-x compile,

bash-completion-dynamic-complete

EMACS_BASH_COMPLETE

t

Completion at point

Additionally, you can enable bash completion in any buffer that contains bash commands. To do that, call

elisp
(bash-completion-dynamic-complete-nocomint COMP-START COMP-POS DYNAMIC-TABLE)

completion-at-point-functions

The trickiest part is setting COMP-START to where the bash command starts; It depends on the mode of the calling buffer and might, in some cases, span multiple lines.

COMP-POS is usually the current position of the cursor.

When calling from

completion-at-point

For example, here's a function to to do bash completion from an eshell buffer. To try it out, add the function below to your init file and bind

bash-completion-from-eshell

(defun bash-completion-from-eshell ()
  (interactive)
  (let ((completion-at-point-functions
         '(bash-completion-eshell-capf)))
    (completion-at-point)))

(defun bash-completion-eshell-capf ()
  (bash-completion-dynamic-complete-nocomint
   (save-excursion (eshell-bol) (point))
   (point) t))

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.
• Did you start a new bash process, with

  exec bash

  or

  sudo

  ? If yes, call

  bash-completion-refresh

  to configure the new bash process.
• Call

  M-x bash-completion-debug

  and look at the completion table at the bottom. Does it match your expectation? If not, call

  M-x bash-completion-refresh

  to refresh the copy of the completion table kept by Emacs, or if you're in a

  M-x execute

  or

  M-x compile

  prompt, call

  M-x bash-completion-reset-all

  , then try again.
• Still on

  M-x bash-completion-debug

  , does the

  output-buffer

  section 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
• If all else fails, file a bug. 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 or even to ask questions, please open an issue. To contribute code or documentation, please open a pull request.

See CONTRIBUTING.md for more details.

COMPATIBILITY

bash-completion.el is known to work with Bash 3, 4 and 5, on Emacs, starting with version 24.3, under Linux and OSX. It does not work on XEmacs.