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


Getting Started

This chapter provides basic instructions for Company setup and usage.


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.


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 a 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).


Usage Basics

By default — having company-mode enabled (see Initial Setup) — a tooltip with completion candidates is shown when a user types in 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 complete with the common part: characters present at the beginning of all the candidates.
  • Hit C-g to stop activity of Company.

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 the 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).

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

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))

Footnotes

(2)

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.


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