-- fill-column: 120 org-list-indent-offset: 1 --
#+TITLE: Company Shell
Company mode completion backends for your shell scripting:
- [[#doc-strings][Doc Strings]]
- [[#excessively-slow-meta-lookup][Excessively slow meta lookup]]
company-shell offers 3 backends for 3 different sources: company-shell- providing completions for binaries that are found on your $PATH company-fish-shell- providing completions for fish-shell's functions, both builtin as well as user-defined company-shell-env- providing completions for environment variables based on the envcommand
** Doc Strings
To find the documentation for a completion candidate /c/
company-shell and company-fish-shell will both first try
the output of man c. If /c/ does not have a manpage they will then use c --help as a fallback. The latter needs
to be enabled manually (see the description about company-shell-use-help-arg below). The meta doc-string (shown in the
minibuffer during completion) is provided by (the first line of) whatis c.
There are no doc- or meta-strings for
As the process of searching though the content of your
$PATH and building the completion lists is likely
to cause a visible delay it is done exactly once - when company-shell is invoked for the first time.
The list of all possible completions will then be saved in the variable company-shell--cache.
company-fish-shell and company-shell-env follow the same pattern, their completions are stored in
company-shell--fish-cache and company-shell--env-cache respectively.
All caches may be manually rebuilt by invoking
company-shell-rebuild-cache. This function may also be used
in e.g. a mode or local save hook to automatically rebuild the completion cache whenever a file of that mode is
company-shellto your company-backends:
#+BEGIN_SRC emacs-lisp (add-to-list 'company-backends 'company-shell) #+END_SRC
To use multiple backends at once add them as a combined backend:
#+BEGIN_SRC emacs-lisp (add-to-list 'company-backends '(company-shell company-shell-env company-fish-shell)) #+END_SRC
To learn more about (combining) backends see the doc-string of
company-shell offers the following configuration options (available under customize-group): company-shell-delete-duplicates(default value: t)
If non-nil the list of
company-shell'scompletions will be purged of duplicates. Duplicates in this context means any two string-equal entries, regardless where they have been found. This would prevent a completion candidate appearing twice because it is found in both /usr/bin and /usr/local/bin. For a change to this variable to take effect the cache needs to be rebuilt via company-shell-rebuild-cache. company-shell-modes(default value: sh-mode fish-mode shell-mode eshell-mode)
List of major modes where
company-shelland company-shell-envwill be providing completions if they are part of company-backends. All modes not on this list will be ignored. Set value to nil to enable company-shellregardless of current major-mode. company-fish-shell-modes(default value: fish-mode shell-mode)
List of major modes where
company-fish-shellwill be providing completions if it is part of company-backends. All modes not on this list will be ignored. Set value to nil to enable company-shellregardless of current major-mode. company-shell-clean-manpage(default value: nil)
When t clean the man-page with ~Man-cleanup-manpage'. This is only needed when you have the problem of your man pages being filled with control characters (you'll know it when you see it).
company-shell-use-help-arg(default value: nil)
SETTING THIS TO t IS POTENTIALLY UNSAFE.
company-(fish)-shellwill try and find a doc-string by running arg --helpif man argdid not produce any valid results. This is not completely safe since company-shelldoes not and can not know whether it is safe to run a command in this fashion. Some applications may simply ignore or misinterpret this argument, with unpredictable results. Usually this just means that instead of any actual documentation you'll see an error message telling you the program doesn't know what to do with the --helparg or that it was started with invalid input. In rare cases a program may simple ignore the --helparg and directly spawn a GUI like xfce4-notes-settings does.
To mitigate any such issues company-shell will run the
--helpattempt on a timer of 1 second. This is more than enough to fetch the doc output if it is available, but will quickly close any process that may accidentally have been spawned. In addition the command will run in a restricted shell (via $(which sh) --restricted) to further avoid any unwanted side effects.
Despite these precautions company-shell will nonetheless need to sometimes run completely unknown binaries, which is why this option is turned off by default. You need to consciously enable it in the understanding that you do this AT YOUR OWN RISK.
** Excessively slow meta lookup
company-shell uses the
whatis shell command to look up meta strings for company-mode. In [[https://github.com/Alexander-Miller/company-shell/issues/15#issuecomment-940227128][some situations]] that may be
extremely slow to the point of rendering company-shell unusable. When that happens you can set
company-shell-dont-fetch-meta to a non-nil value to prevent the lookup from happening.