Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Alexander-Miller/company-shell


https://github.com/Alexander-Miller/company-shell

autocompletion company-mode emacs fish-shell shell-script

Last synced: about 1 month ago
JSON representation

Awesome Lists containing this project

README 

        
# -*- fill-column: 120 org-list-indent-offset: 1 -*-



#+STARTUP: noinlineimages



#+TITLE: Company Shell



[[https://melpa.org/#/company-shell][file:https://melpa.org/packages/company-shell-badge.svg]] [[https://stable.melpa.org/#/company-shell][file:https://stable.melpa.org/packages/company-shell-badge.svg]]



Company mode completion backends for your shell scripting:



[[file:screenshot.png]]



* Content                                                                            :TOC:noexport:

- [[#features][Features]]

   - [[#backends][Backends]]

   - [[#doc-strings][Doc Strings]]

   - [[#caching][Caching]]

- [[#setup][Setup]]

- [[#configuration][Configuration]]

   - [[#excessively-slow-meta-lookup][Excessively slow meta lookup]]

- [[#dependencies][Dependencies]]



* Features

** Backends



~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 ~env~ command



** 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 ~company-shell-env~.



** Caching



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

opened.



* Setup



 * Single backend



   Add e.g. ~company-shell~ to your ~company-backends~:



   #+BEGIN_SRC emacs-lisp

     (add-to-list 'company-backends 'company-shell)

   #+END_SRC



 * Multiple backends



   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-backends~.



* Configuration



~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's~ completions 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-shell~ and ~company-shell-env~ will 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-shell~ regardless

   of current major-mode.



 * ~company-fish-shell-modes~ (default value: fish-mode shell-mode)



   List of major modes where ~company-fish-shell~ will 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-shell~ regardless 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.



   If non-nil ~company-(fish)-shell~ will try and find a doc-string by running ~arg --help~

   if ~man arg~ did not produce any valid results. This is not completely safe since

   ~company-shell~ does 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

   ~--help~ arg or that it was started with invalid input. In rare cases a program may simple

   ignore the ~--help~ arg and directly spawn a GUI like xfce4-notes-settings does.



   To mitigate any such issues company-shell will run the ~--help~ attempt 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.



 * ~company-shell-complete-in-comments~ (default value: t)



   Indicates whether completions should be offered inside comments.



** 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.



* Dependencies

 * company

 * cl-lib

 * dash