Company User Manual

Next:   [Contents]

Company

Company is a modular text completion framework for GNU Emacs.

The goal of this document is to lay out the foundational knowledge of the package, so that the readers of the manual could competently start adapting Company to their needs and preferences.

This user manual is for Company version 1.0.0 (21 September 2024).

Copyright © 2021-2024 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation.

Table of Contents


Next: , Previous: , Up: Company   [Contents]

1 Overview

Company is a modular text completion framework for GNU Emacs.

In other words, it is a package for retrieving, manipulating, and displaying text completion candidates. It aims to assist developers, writers, and scientists during code and text writing.


Next: , Up: Overview   [Contents]

1.1 Terminology

Completion is an act of intelligently guessing possible variants of words based on already typed characters. To complete a word means to insert a correctly guessed variant into the buffer.

Consequently, the candidates are the aforementioned guessed variants of words. Each of the candidates has the potential to be chosen for successful completion. And each of the candidates contains the initially typed characters: either only at the beginning (so-called prefix matches), or also inside of a candidate (non-prefix matches). Which matching method is used, depends on the current backend (see Structure). company-capf is an example of a backend that supports a number of particular non-prefix matching algorithms which are configurable through the user option completion-styles, which see. For illustrations on how Company visualizes the matches, see Frontends.

The package’s name ‘Company’ is based on the combination of the two words: ‘Complete’ and ‘Anything’. These words reflect the package’s commitment to handling completion candidates and its extensible nature allowing it to cover a wide range of usage scenarios.


Previous: , Up: Overview   [Contents]

1.2 Structure

The Company is easily extensible because its significant building blocks are pluggable modules: backends (see Backends) and frontends (see Frontends).

The backends are responsible for retrieving completion candidates; which are then displayed by the frontends. For an easy and quick initial setup, Company is supplied with the preconfigured sets of the backends and frontends. The default behavior of the modules can be adjusted for particular needs, and preferences. It is also typical to utilize backends from a variety of third-party libraries, developed to be pluggable with Company.

But Company consists not only of the backends and frontends.

A core of the package plays the role of a controller, connecting the modules, making them work together; and exposing configurations and commands for the user to operate with. For more details, Customization and Commands.

Also, Company is bundled with an alternative workflow configuration company-tng — defining company-tng-frontend, company-tng-mode, and company-tng-map — that allows performing completion with just TAB. To enable this configuration, add the following line to the Emacs initialization file (see (emacs)Init File):

(add-hook 'after-init-hook 'company-tng-mode)

Next: , Previous: , Up: Company   [Contents]

2 Getting Started

This chapter provides basic instructions for Company setup and usage.


2.1 Installation

Company package is distributed via commonly used package archives in a form of both stable and development releases. To install Company, type M-x package-install RET company RET.

For more details on Emacs package archives, see (emacs)Packages.


Next: , Previous: , Up: Getting Started   [Contents]

2.2 Initial Setup

The package Company provides a minor mode company-mode.

To activate the company-mode, execute the command M-x company-mode that toggles the mode on and off. When it is switched on, the mode line (see (emacs)Mode line) should indicate its presence with an indicator ‘company’.

After company-mode had been enabled, the package auto-starts suggesting completion candidates. The candidates are retrieved and shown according to the typed characters and the default (until the user specifies otherwise) configurations.

To have Company always enabled for the following sessions, add the line (global-company-mode) to the Emacs configuration file (see (emacs)Init File).


Next: , Previous: , Up: Getting Started   [Contents]

2.3 Usage Basics

By default — having company-mode enabled (see Initial Setup) — a tooltip with completion candidates is shown when the user types a few characters.

To initiate completion manually, use the command M-x company-complete.

To select next or previous of the shown completion candidates, use respectively key bindings C-n and C-p, then do one of the following:

  • Hit RET to choose a selected candidate for completion.
  • Hit TAB to expand the common part of all completions. Exactly what that means, can vary by backend. In the simplest case it’s the longest string that all completion start with, but when a backend returns non-prefix matches, it can implement the same kind of expansion logic for the input string.
  • Hit C-g to stop activity of Company.

Previous: , Up: Getting Started   [Contents]

2.4 Commands

Under the hood, mentioned in the previous section keys are bound to the commands of the out-of-the-box Company.

C-n
M-n

Select the next candidate (company-select-next-or-abort, company-select-next).

C-p
M-p

Select the previous candidate (company-select-previous-or-abort, company-select-previous).

RET
<return>

Insert the selected candidate (company-complete-selection).

TAB
<tab>

Insert the common part of all completion candidates (company-complete-common).

C-g
<ESC ESC ESC>

Cancel company-mode activity (company-abort).

C-h
<F1>

Display a buffer with the documentation for the selected candidate (company-show-doc-buffer). With a prefix argument (C-u C-h, C-u F1), this command toggles between temporary showing the documentation and keeping the documentation buffer up-to-date whenever the selection changes.

C-w

Display a buffer with the definition of the selected candidate (company-show-location).

The full list of the default key bindings is stored in the variables company-active-map and company-search-map 1.

Moreover, Company is bundled with a number of convenience commands that do not have default key bindings defined. The following examples illustrate how to assign key bindings to such commands.

(global-set-key (kbd "<tab>") #'company-indent-or-complete-common)
(with-eval-after-load 'company
  (define-key company-active-map (kbd "M-/") #'company-complete))
(with-eval-after-load 'company
  (define-key company-active-map
              (kbd "TAB")
              #'company-complete-common-or-cycle)
  (define-key company-active-map
              (kbd "<backtab>")
              (lambda ()
                (interactive)
                (company-complete-common-or-cycle -1))))

In the same manner, an additional key can be assigned to a command or a command can be unbound from a key. For instance:

(with-eval-after-load 'company
  (define-key company-active-map (kbd "M-.") #'company-show-location)
  (define-key company-active-map (kbd "RET") nil))

Next: , Previous: , Up: Company   [Contents]

3 Customization

Emacs provides two equally acceptable ways for user preferences configuration: via customization interface (for more details, see (emacs)Easy Customization) and a configuration file (see (emacs)Init File). Naturally, Company can be configured by both of these approaches.


3.1 Customization Interface

In order to employ the customization interface, run M-x customize-group RET company.

This interface outputs all the options available for user customization, so you may find it beneficial to review this list even if you are going to configure Company with the configuration file.

For instructions on how to change the settings, see (emacs)Changing a Variable.


3.2 Configuration File

Company is a customization-rich package. This section lists some of the core settings that influence its overall behavior.

User Option: company-minimum-prefix-length

This is one of the values (together with company-idle-delay), based on which Company auto-stars looking up completion candidates. This option configures how many characters have to be typed in by a user before candidates start to be collected and displayed. An often choice nowadays is to configure this option to a lower number than the default value of 3.

User Option: company-idle-delay

This is the second of the options that configure Company’s auto-start behavior (together with company-minimum-prefix-length). The value of this option defines how fast Company is going to react to the typed input, such that setting company-idle-delay to 0 makes Company react immediately, nil disables auto-starting, and a larger value postpones completion auto-start for that number of seconds. For an even fancier setup, set this option value to a predicate function, as shown in the following example:

(setq company-idle-delay
      (lambda () (if (company-in-string-or-comment) nil 0.3)))
User Option: company-inhibit-inside-symbols

You can set this option to t to disable the auto-start behavior when in the middle of a symbol.

User Option: company-global-modes

This option allows to specify in which major modes company-mode can be enabled by (global-company-mode). See Initial Setup. The default value of t enables Company in all major modes. Setting company-global-modes to nil equal in action to toggling off global-company-mode. Providing a list of major modes results in having company-mode enabled in the listed modes only. For the opposite result, provide a list of major modes with not being the first element of the list, as shown in the following example:

(setq company-global-modes '(not erc-mode message-mode eshell-mode))
User Option: company-selection-wrap-around

Enable this option to loop (cycle) the candidates’ selection: after selecting the last candidate on the list, a command to select the next candidate does so with the first candidate. By default, this option is disabled, which means the selection of the next candidate stops on the last item. The selection of the previous candidate is influenced by this option similarly.

User Option: company-require-match

To allow typing in characters that don’t match the candidates, set the value of this option to nil. For an opposite behavior (that is, to disallow non-matching input), set it to t. By default, Company is configured to require a matching input only if the user invokes completion manually or selects a candidate; by having the option configured to call the function company-explicit-action-p.

User Option: company-lighter-base

This user options allows to configure a string indicator of the enabled company-mode in the mode line. The default value is ‘company’.

User Option: company-insertion-on-trigger

One more pair of the user options may instruct Company to complete with the selected candidate by typing one of the company-insertion-triggers. The user option company-insertion-on-trigger can be enabled or disabled by setting its value to one of: nil, t, or a predicate function name. See (eintr)Predicate.

User Option: company-insertion-triggers

This option has an effect only when company-insertion-on-trigger is enabled. The value can be one of: a string of characters, a list of syntax description characters (see (elisp)Syntax Class Table), or a predicate function. By default, this user option is set to the list of the syntax characters: (?\ ?\) ?.), which translates to the whitespaces, close parenthesis, and punctuation. It is safe to configure the value to a character that can potentially be part of a valid completion; in this case, Company does not treat such characters as triggers.

Hooks

Company exposes the following life-cycle hooks:

User Option: company-completion-started-hook
User Option: company-completion-cancelled-hook
User Option: company-completion-finished-hook
User Option: company-after-completion-hook

Next: , Previous: , Up: Company   [Contents]

4 Frontends

Company is packaged with several frontends and provides a predefined set of enabled frontends. A list of the enabled frontends can be changed by configuring the user option company-frontends.

Each frontend is simply a function that receives a command and acts accordingly to it: outputs candidates, hides its output, refreshes displayed data, and so on.

All of the Company frontends can be categorized by the type of the output into the three groups: tooltip-, preview-, and echo- frontends. We overview these groups in the first sections of this chapter. The sections that follow are dedicated to the ways the displayed candidates can be searched, filtered, and quick-accessed.


4.1 Tooltip Frontends

This group of frontends displays completion candidates in an overlayed tooltip (aka pop-up). Company provides three tooltip frontends, listed below.

Function: company-pseudo-tooltip-unless-just-one-frontend

This is one of the default frontends. It starts displaying a tooltip only if more than one completion candidate is available, which nicely combines — and it is done so by default — with company-preview-if-just-one-frontend, Preview Frontends.

Function: company-pseudo-tooltip-frontend

This frontend outputs a tooltip for any number of completion candidates.

Function: company-pseudo-tooltip-unless-just-one-frontend-with-delay

This is a peculiar frontend, that displays a tooltip only if more than one candidate is available, and only after a delay. The delay can be configured with the user option company-tooltip-idle-delay. A typical use case for plugging in this frontend would be displaying a tooltip only on a manual request (when needed), as shown in the following example:

(setq company-idle-delay 0
      company-tooltip-idle-delay 10
      company-require-match nil
      company-frontends
      '(company-pseudo-tooltip-unless-just-one-frontend-with-delay
        company-preview-frontend
        company-echo-metadata-frontend)
      company-backends '(company-capf))

(global-set-key (kbd "<tab>")
                (lambda ()
                  (interactive)
                  (let ((company-tooltip-idle-delay 0.0))
                    (company-complete)
                    (and company-candidates
                         (company-call-frontends 'post-command)))))

User Options

To change the tooltip frontends configuration, adjust the following user options.

User Option: company-tooltip-align-annotations

An annotation is a string that carries additional information about a candidate; such as a data type, function arguments, or whatever a backend appoints to be a valuable piece of information about a candidate. By default, the annotations are shown right beside the candidates. Setting the option value to t aligns annotations to the right side of the tooltip.

(setq company-tooltip-align-annotations t)
./images/large/tooltip-annotations
User Option: company-tooltip-annotation-padding

Adds left padding to the candidates’ annotations. It is disabled by default. If company-tooltip-align-annotations is enabled, company-tooltip-annotation-padding defines the minimum spacing between a candidate and annotation, with the default value of 1.

(setq company-tooltip-annotation-padding 1)
User Option: company-tooltip-limit

Controls the maximum number of the candidates shown simultaneously in the tooltip (the default value is 10). When the number of the available candidates is larger than this option’s value, Company paginates the results.

(setq company-tooltip-limit 4)
./images/large/tooltip-limit
User Option: company-tooltip-offset-display

Use this option to choose in which way to output paginated results. The default value is ‘scrollbar’. Another supported value is ‘lines’; choose it to show the quantity of the candidates not displayed by the current tooltip page.

(setq company-tooltip-offset-display 'lines)
./images/large/tooltip-offset-display
User Option: company-tooltip-minimum

This user option acts only when a tooltip is shown close to the bottom of a window. It guarantees visibility of this number of completion candidates below point. When the number of lines between point and the bottom of a window is less than company-tooltip-minimum value, the tooltip is displayed above point.

(setq company-tooltip-minimum 4)
./images/large/tooltip-minimum-below ./images/large/tooltip-minimum-above
User Option: company-tooltip-flip-when-above

When this setting is enabled, no matter if a tooltip is shown above or below point, the candidates are always listed starting near point. (Putting it differently, the candidates are mirrored vertically if a tooltip changes its position, instead of being commonly listed top-to-bottom.)

(setq company-tooltip-flip-when-above t)
./images/large/tooltip-flip
User Option: company-tooltip-minimum-width

Sets the minimum width of a tooltip, excluding the margins and the scroll bar. Changing this value especially makes sense if the user navigates between tooltip pages. Keeping this value at the default 0 allows Company to always adapt the width of the tooltip to the longest shown candidate. Enlarging company-tooltip-minimum-width prevents possible significant shifts in the width of the tooltip when navigating to the next/previous tooltip page. (For an alternate solution, see company-tooltip-width-grow-only.)

User Option: company-tooltip-width-grow-only

This is another way to restrict auto-adaptation of the tooltip width (another is by adjusting company-tooltip-minimum-width value) when navigating between the tooltip pages.

User Option: company-tooltip-maximum-width

This user option controls the maximum width of the tooltip inner area. By default, its value is pseudo-limitless, potentially permitting the output of extremely long candidates. But if long lines become an issue, set this option to a smaller number, such as 60 or 70.

User Option: company-tooltip-margin

Controls the width of the margin on the sides of the tooltip inner area. If company-format-margin-function is set, company-tooltip-margin defines only the right margin.

(setq company-tooltip-margin 3)
./images/large/tooltip-margin

Candidates Icons

An icon is an image or a text that represents a candidate’s kind; it is displayed in front of a candidate. The term kind here stands for a high-level category a candidate fits into. (Such as ‘array’, ‘function’, ‘file’, ‘string’, ‘color’, etc. For an extended list of the possible kinds, see the user option company-text-icons-mapping or the variable company-vscode-icons-mapping.)

User Option: company-format-margin-function

Allows setting a function to format the left margin of a tooltip inner area; namely, to output candidate’s icons. The predefined formatting functions are listed below. The user may also set this option to a custom function. To disable left margin formatting, set the value of the option to nil (this way control over the size of the left margin returns to the user option company-tooltip-margin).

Function: company-vscode-dark-icons-margin
Function: company-vscode-light-icons-margin

These functions utilize VSCode dark and light theme icon sets 2. The related two user options are company-icon-size and company-icon-margin.

./images/large/tooltip-icons-vscode
Function: company-text-icons-margin

This function produces letters and symbols formatted according to the company-text-icons-format. The rest of the user options affecting this function behavior are listed below.

./images/large/tooltip-icons-text
Function: company-dot-icons-margin

This function produces a colored Unicode symbol of a circle formatted according to the company-dot-icons-format. Other user options that affect the resulting output are listed below.

./images/large/tooltip-icons-dot

The following user options influence appearance of the text and dot icons.

User Option: company-text-icons-mapping

Lists candidates’ kinds with their corresponding icons configurations.

User Option: company-text-face-extra-attributes

A list of face attributes to be applied to the icons.

(setq company-text-face-extra-attributes
      '(:weight bold :slant italic))
./images/large/tooltip-icon-face
User Option: company-text-icons-add-background

If this option is enabled, when an icon doesn’t have a background configured by company-text-icons-mapping, then a generated background is applied.

(setq company-text-icons-add-background t)
./images/large/tooltip-icon-bg
Function: company-detect-icons-margin

This is the default margin formatting function, that applies one of the company-vscode-*-icons-margin functions if ‘vscode’ icons set is supported; otherwise applies a company-text-icons-margin function.

Faces

Out-of-the-box Company defines and configures distinguished faces (see (emacs)Faces) for light and dark themes. Moreover, some of the built-in and third-party themes fine-tune Company to fit their palettes. That is why there’s often no real need to make such adjustments on the user’s side. However, this chapter presents some hints on where to start customizing Company interface.

Namely, the look of a tooltip is controlled by the company-tooltip* named faces.

The following example suggests how users may approach tooltip faces customization:

(custom-set-faces
 '(company-tooltip
   ((t (:background "ivory" :foreground "MistyRose3"))))
 '(company-tooltip-selection
   ((t (:background "LemonChiffon1" :foreground "MistyRose4"))))
 '(company-tooltip-common ((t (:weight bold :foreground "pink1"))))
 '(company-scrollbar-fg ((t (:background "ivory3"))))
 '(company-scrollbar-bg ((t (:background "ivory2"))))
 '(company-tooltip-annotation ((t (:foreground "MistyRose2")))))
./images/large/tooltip-faces-light

Next: , Previous: , Up: Frontends   [Contents]

4.2 Preview Frontends

Frontends in this group output a completion candidate or a common part of the candidates temporarily inline, as if the word had already been completed 3.

Function: company-preview-if-just-one-frontend

This is one of the frontends enabled by default. This frontend outputs a preview if only one completion candidate is available; it is a good suit to be combined with company-pseudo-tooltip-unless-just-one-frontend, Tooltip Frontends.

Function: company-preview-frontend

This frontend outputs the first of the available completion candidates inline for a preview.

Function: company-preview-common-frontend

As the name of this frontend suggests, it outputs for a preview only a common part of the candidates.

The look of the preview is controlled by the following faces: company-preview, company-preview-common, and company-preview-search.

./images/large/preview-light ./images/large/preview-dark

4.3 Echo Frontends

The frontends listed in this section display information in the Emacs’s echo area, (emacs)Echo Area.

Function: company-echo-metadata-frontend

This frontend is a part of the predefined frontends set. Its responsibility is to output a short documentation string for a completion candidate in the echo area.

./images/large/echo-meta

The last pair of the built-in frontends isn’t that commonly used and not as full-featured as the previously reviewed tooltip- and preview- frontends, but still, feel free to play with them and have some fun!

Function: company-echo-frontend

This frontend outputs all the available completion candidates in the echo area.

./images/large/echo
Function: company-echo-strip-common-frontend

It acts similarly to the previous frontend but outputs a common part of the candidates once for all of them.

./images/large/echo-strip
User Option: company-echo-truncate-lines

This is the only echo frontends targeted setting. When enabled, the output is truncated to fit the echo area. This setting is set to t by default.

To apply visual changes to the output of these frontends, configure the faces company-echo and company-echo-common.


4.5 Filter Candidates

Candidates filtering is started by typing the default key binding C-M-s. Filtering acts on a par with the search (see Candidates Search), indicating its activation by the text ‘Filter: CHARACTERS in the mode line and influencing the displayed candidates. The difference is that the filtering, as its name suggests, keeps displaying only the matching candidates (in addition to distinguishing the matches with a face).

To quit the filtering, hit C-g. To toggle between search and filter states, use key binding C-o.

./images/large/tooltip-filter

Previous: , Up: Frontends   [Contents]

4.6 Quick Access a Candidate

Company provides a way to choose a candidate for completion without having to navigate to that candidate: by hitting one of the quick-access keys. By default, quick-access key bindings utilize a modifier META and one of the digits, such that pressing M-1 completes with the first candidate on the list and M-0 with the tenth candidate.

If company-show-quick-access is enabled, tooltip- and echo- frontends show quick-access hints.

(setq company-show-quick-access 'left)
./images/large/tooltip-quick-access ./images/large/echo-qa ./images/large/echo-strip-qa

To customize the key bindings, either do it via Customization Interface (see Customization Interface) or use the following approach:

(custom-set-variables
 '(company-quick-access-keys '("a" "o" "e" "u" "i"))
 '(company-quick-access-modifier 'super))

A modifier should be one of meta, super, hyper, control.

The following example applies a bit of customization and demonstrates how to change quick-access hints faces.

(setq company-show-quick-access t)

(custom-set-faces
 '(company-tooltip-quick-access ((t (:foreground "pink1"))))
 '(company-tooltip-quick-access-selection
   ((t (:foreground "pink1" :slant italic)))))
./images/large/tooltip-qa-faces-light

Next: , Previous: , Up: Company   [Contents]

5 Backends

We can metaphorically say that each backend is like an engine. (The reality is even better since backends are just functions.) Firing such an engine with a command causes the production of material for Company to work on. Typically, that means showing that output to the user via one or several configured frontends, Frontends.

Just like Company provides a preconfigured list of the enabled frontends, it also defines a list of the backends to rely on by default. This list is stored in the user option company-backends. The docstring of this variable has the full description of what a backend is and how to implement one. So we suggest reading the output of C-h v company-backends for more details. Nevertheless, the fundamental concepts are described in this user manual too.


5.1 Backends Usage Basics

One of the significant concepts to understand about Company is that the package relies on one backend at a time 4. The backends are invoked one by one, in the sequential order of the items on the company-backends list. The first one that reports itself applicable in the current context (usually based on the value of major-mode and the text around point), is used for completion.

The name of the currently active backend is shown in the mode line and in the output of the command M-x company-diag.

In most cases (mainly to exclude false-positive results), if the current applicable backend returned no completions, the ones after it in the list are not invoked. If you do want to query the next one, use the command company-other-backend: either by calling it with M-x or by binding the command to the keys of your choice, like:

(global-set-key (kbd "C-c C-/") #'company-other-backend)

It is also possible to specifically start a backend with the command M-x company-begin-backend or by calling a backend by its name, for instance: M-x company-capf. As usual for Emacs, such backends calls can be assigned to key bindings, for example:

(global-set-key (kbd "C-c y") 'company-yasnippet)

5.2 Grouped Backends

In many cases, it can be desirable to receive candidates from several backends simultaneously. This can be achieved by configuring grouped backends: a sub-list of backends in the company-backends list, that is handled specifically by Company.

The most important part of this handling is the merge of the completion candidates from the grouped backends.

To keep the candidates organized in accordance with the grouped backends order, add the keyword :separate to the list of the grouped backends. The following example illustrates this.

(defun my-text-mode-hook ()
  (setq-local company-backends
              '((company-dabbrev company-ispell :separate)
                company-files)))

(add-hook 'text-mode-hook #'my-text-mode-hook)

Another keyword :with helps to make sure the results from major/minor mode agnostic backends (such as company-yasnippet, company-dabbrev-code) are returned without preventing results from context-aware backends (such as company-capf or company-clang). For this feature to work, put backends dependent on a mode at the beginning of the grouped backends list, then put a keyword :with, and only then put context agnostic backend(s), as shown in the following concise example:

(setq company-backends '((company-capf :with company-yasnippet)))

5.3 Package Backends

The following sections give a short overview of the commonly used backends bundled with Company. Each section is devoted to one of the roughly outlined groups of the backends.

Some of the backends expose user options for customization; a few of these options are introduced below. For those who would like to fetch the full list of a backend’s user options, we suggest doing one of the following:

  • Execute command M-x customize-group RET <backend-name>.
  • Open the source file of the backend and run M-x occur RET ^(defcustom.
    • - Optionally, search for the matches with M-x isearch RET (defcustom.

5.3.1 Code Completion

Function: company-capf

The current trend in the Emacs’s world is to delegate completion logic to the hook completion-at-point-functions (CAPF) assigned to by the major or minor modes. It supports a common subset of features which is well-supported across different completion UIs. [Among other things, this is what the most popular Emacs clients for the language server protocol (LSP) also rely on.]

For that reason, it is probably the most used and recommended backend nowadays, including for Emacs Lisp coding.

Just to illustrate, the following minimal backends setup

(setq company-backends '((company-capf company-dabbrev-code)))

might cover a large number of basic use cases, especially so in major modes that have CAPF support implemented.

For more details on CAPF, (elisp)Completion in Buffers.

User Option: company-capf-disabled-functions

List of completion functions which should be ignored by this backend. By default it contains the functions that duplicate the built-in backends but don’t support the corresponding configuration options and/or alter the intended priority of the default backends’ configuration.

Function: company-dabbrev-code

This backend works similarly to the built-in Emacs package dabbrev, searching for completion candidates inside the contents of the open buffer(s). Internally, it reuses code from the other backend, company-dabbrev (see Text Completion).

User Option: company-dabbrev-code-modes

This variable lists the modes that use company-dabbrev-code. The backend will only perform completion in these major modes and their derivatives. Otherwise it passes control to other backends. Value t means complete in all modes.

User Option: company-dabbrev-code-other-buffers

This variable determined whether company-dabbrev-code will search other buffers for completions. If all, it will search all other buffers except the ignored ones (names starting with a space). If t, it will search buffers with the same major mode. If code, it will search buffers with major modes in company-dabbrev-code-modes or derived from one of them. This can also be a function that takes the current buffer as parameter and returns a list of major modes to search.

User Option: company-dabbrev-code-everywhere

This is a boolean option which determines whether this backend will perform completion in strings and comments as well. The default value nil means it will pass on control to other backends in such contexts.

User Option: company-dabbrev-code-completion-styles

Non-nil to use completion-styles for matching completions in this backend. It can be set to t to use the global value of completion-styles, or to a list of symbols to use specific completion styles with this backend. The default value is nil.

Function: company-keywords

This backend provides completions for many of the widely spread programming languages keywords: words bearing specific meaning in a language.

Function: company-clang

As the name suggests, use this backend to get completions from Clang compiler; that is, for the languages in the C language family: C, C++, Objective-C. It uses the command-line interface of the program clang, but without any advanced caching across calls, or automatic detection of the project structure. Which makes it more suitable for small to medium projects, especially if you’re willing to customize company-clang-arguments. Otherwise we recommend using one of the LSP clients available for Emacs, together with the backend company-capf.

User Option: company-clang-arguments

This option can be set to a list of strings which will be passed to clang during completion. These can include elements like "-I" "path/to/includes/dir" to indicate the header directories and other compiler options.

Function: company-semantic

This backend relies on a built-in Emacs package that provides language-aware editing commands based on source code parsers, (emacs)Semantic. Having enabled semantic-mode makes it to be used by the CAPF mechanism (see (emacs)Symbol Completion), hence the user may consider enabling company-capf backend instead.

Function: company-etags

This backend uses tags tables as produced by the built-in Emacs program etags, (emacs)Tags Tables.

User Option: company-etags-ignore-case

Non-nil to ignore case in this backend’s completions.

User Option: company-etags-everywhere

Non-nil to offer completions in comments and strings. It can also be set to t or a list of major modes in which this would happen.

User Option: company-etags-completion-styles

Non-nil to use completion-styles for matching completions in this backend. It can be set to t to use the global value of completion-styles, or to a list of symbols to use specific completion styles with this backend. The default value is nil.


5.3.2 Text Completion

Function: company-dabbrev

This backend works similarly to the built-in Emacs package dabbrev, searching for completion candidates inside the contents of the open buffer(s). It is one of the often used backends, and it has several interesting options for configuration. Let’s review a few of them.

User Option: company-dabbrev-minimum-length

This option sets the minimum length of a completion candidate to collect from the text. The default value of ‘4’ is intended to prevent potential performance issues. But in many scenarios, it may be acceptable to lower this value. Note that this option also affects the behavior of the company-dabbrev-code backend.

(setq company-dabbrev-minimum-length 2)
User Option: company-dabbrev-other-buffers

By default, company-dabbrev collects completion candidates from all not ignored buffers (see more on that below). This behavior can be changed to collecting candidates from the current buffer only (by setting the value to ‘nil’) or from the buffers with the same major mode:

(setq company-dabbrev-other-buffers t)
User Option: company-dabbrev-ignore-buffers

The value of this option should be a regexp or a predicate function that can be used to match a buffer name. The matched buffers are omitted from the search for completion candidates.

The last two options described here relate to handling uppercase and lowercase letters in completion candidates. The illustrative examples given below can be reproduced in the ‘*scratch*’ buffer, with the word ‘Enjoy’ typed in, and with this initial setup:

(setq-local company-backends '(company-dabbrev)
            company-dabbrev-other-buffers nil
            company-dabbrev-ignore-case nil
            company-dabbrev-downcase nil)
User Option: company-dabbrev-ignore-case

This user option controls whether the case is ignored when collecting completion candidates. When the option is set to nil, ‘Enjoy’ is suggested as a completion candidate for the typed ‘Enj’ letters, but not for ‘enj’. When the option is set to t, ‘Enjoy’ is suggested as a candidate for both ‘Enj’ and ‘enj’ input; note that ‘enj’ prefix is “overwritten” by completing with the ‘Enjoy’ candidate. The third, default, type of behavior solves this issue, keeping the case of the typed prefix (and still collecting candidates case-insensitively):

(setq company-dabbrev-ignore-case 'keep-prefix)

Now we can type ‘enj’, complete it with the suggested ‘Enjoy’, and enjoy the result.

User Option: company-dabbrev-downcase

This user option controls whether completion candidates are down-cased before their display. When the option is set to nil, no transformation is performed; in the environment described above, typing ‘Enj’ results in the candidate ‘Enjoy’ being suggested. When the option is set to t, the down-cased candidate ‘enjoy’ is suggested. By default, this option is set to case-replace, meaning taking a value of the Emacs’s variable case-replace (t is the current default).


Function: company-ispell

This backend returns completion candidates collected by Ispell, a built-in Emacs package that performs spell-checking. See (emacs)Checking and Correcting Spelling. Note that Ispell uses only one dictionary at a time (combining several dictionaries into one file is an accepted practice). By default, company-ispell suggests candidates from a dictionary specified by the Emacs’s setting ispell-complete-word-dict.

User Option: company-ispell-dictionary

Optionally, set a file path for company-ispell to use another dictionary.


5.3.3 File Name Completion

Function: company-files

This backend can be used to retrieve completion candidates for the absolute and relative paths in the directory structure of an operating system. The behavior of the company-files backend can be adjusted with the two user options.

User Option: company-files-exclusions

It may be desirable to exclude directories or files from the list of suggested completion candidates. For example, someone’s setup might look this way:

(setq company-files-exclusions '(".git/" ".DS_Store"))
User Option: company-files-chop-trailing-slash

This setting is enabled by default, which results in stripping off a trailing slash from an inserted directory name. On typing a trailing slash, the process of completion gets started again, from inside the just inserted directory.

Setting company-files-chop-trailing-slash to nil makes directory names to be inserted as is, with a trailing slash. In this case, the completion process can be continued, for example, either by explicitly calling company-files backend (see Backends Usage Basics) or by starting typing a name of a file/directory known to be located under the inserted directory.


5.3.4 Template Expansion

Function: company-abbrev

This is a completion backend for a built-in word abbreviation mode (see (emacs)Abbrevs), that allows completing abbreviations with their expansions.

Function: company-tempo

A backend for users of Tempo, one more built-in Emacs package for creating and inserting (expanding) templates.

Function: company-yasnippet

Used as a completion backend for the popular third-party template system YASnippet.


Previous: , Up: Backends   [Contents]

5.4 Candidates Post-Processing

A list of completion candidates, supplied by a backend, can be additionally manipulated (reorganized, reduced, sorted, etc) before its output. This is done by adding a processing function name to the user option company-transformers list, for example:

(setq company-transformers '(delete-consecutive-dups
                             company-sort-by-occurrence))

Company is bundled with several such transformer functions. They are listed below.

Function: company-sort-by-occurrence

Sorts candidates using company-occurrence-weight-function algorithm.

User Option: company-occurrence-weight-function

Can be set to one of company-occurrence-prefer-closest-above (default) or company-occurrence-prefer-any-closest. This user option defines the behavior of the company-sort-by-occurrence transformer function.

Function: company-sort-by-backend-importance

Sorts candidates as two priority groups, differentiated by the keyword :with (see Grouped Backends). Backends positioned in the backends list before the keyword :with are treated as more important.

Function: company-sort-prefer-same-case-prefix

Gives preference to the candidates that match the prefix case-insensitively.


Previous: , Up: Company   [Contents]

6 Troubleshooting

If something goes wrong, the first thing we recommend doing is to execute command M-x company-diag and thoroughly study its output.

This command outputs important details about the internal workings of Company at the moment of the company-diag command execution, including a responsible backend and a list of completion candidates provided by it.

Based on the value of the ‘Used backend’ in the output of the command M-x company-diag, these possible actions may follow:

If the aforementioned steps didn’t help to find the cause of the issue, then file a bug report to the Company Issue Tracker, attaching the following information:

  1. Output of the M-x company-diag.
  2. The exact error message: you can find it in the *Messages* buffer.
  3. The steps to reproduce the behavior. Ideally, if you can, starting with a bare Emacs session: emacs -Q.
  4. The backtrace of the error, which you can get by running the command: M-x toggle-debug-on-error before reproducing the error.

Footnotes

(1)

For a more user-friendly output of the pre-defined key bindings, utilize M-x describe-keymap RET company-active-map or C-h f RET company-mode.

(2)

SVG images support has to be enabled in Emacs for these icons set to be used. The supported images types can be checked with C-h v image-types. Before compiling Emacs, make sure ‘librsvg’ is installed on your system.

(3)

The candidates retrieved according to non-prefix matches (see Terminology) may be shown in full after point.

(4)

The grouped backends act as one complex backend. See Grouped Backends.