/helm

Home

Jump to bottom
Alex P edited this page Sep 22, 2018 · 23 revisions

Table of Contents

Install

From MELPA

Helm is available on two major package.el community-maintained repos: MELPA and MELPA Stable. Follow the instructions to set up the MELPA (Stable) repository.

Install Helm with M-x package-install RET helm RET.

Note: always restart Emacs after reinstalling Helm (or other packages) for the updates to take effect.

Potential issues

Helm upgrades from MELPA encountered errors because of the way the Emacs package manager fetched and compiled updates for existing packages.

To get around these errors, Helm has emacs-async as a dependency. emacs-async forces compilation in a clean environment, which resolves the compilation errors.

From source

Helm needs emacs-async and popup-el as dependencies, install them somewhere in your load-path.

NOTE: When installing emacs-async from sources you should install it using make and make install to ensure helm will find it when running make, otherwise you will have to specify its location from the command line, see below.

To install Helm, get the files from the helm git repo (see the tagged releases for older versions) with git (see command below) or by downloading an archive and decompressing it.

git clone https://github.com/emacs-helm/helm

Then go to the resulting Helm directory and run

make

and

sudo make install

NOTE: Since helm version 2.7.0, helm wont compile with just make if you have installed emacs-async in a non standard location, in that case you will have to specify where emacs-async live on the command line, with the EMACSLOADPATH environment variable.

So after downloading, go to the resulting Helm directory and run

EMACSLOADPATH="/path/to/emacs-async:" make

Don’t forget the final “:” to not override other load-paths and use an absolute path not abbreviated, i.e /home/you/foo/bar: and not ~/foo/bar: to specify EMACSLOADPATH.

Configure

If installed via the Emacs package manager, add the following to your init file:

(require 'helm-config)

If installed from source, add the following:

(add-to-list 'load-path "/path/to/helm/directory") ; facultative when installed with make install
(require 'helm-config)

This will do same basic preparation (load autoloads for example), but it will not load Helm or turn on the Helm minor mode.

For further configuration like changing bindings in the helm-map you will likely want to use a delayed method like with-eval-after-load to avoid loading all of Helm at startup.

General concept

People often think helm is just something like ido but displaying completion in a vertical layout instead of an horizontal one, it is not, helm is much more powerful than that.

  • Helm is able to complete multiple lists dispatched in different sources against a pattern.
  • Helm allows executing an unlimited number of actions on candidates.
  • Helm allows marking candidates to execute chosen action against this set of candidates.
  • Helm can display its completion buffer in different window layouts and in separate frame.

However Helm is divided in two distinct categories of commands, the helm natives commands that provide a feature not existing in Emacs or a new implementation of an existing Emacs feature and the helmized commands that are Emacs native commands modified by helm-mode to provide helm completion and only that. When both are provided e.g switch-to-buffer vs helm-buffers-list you will prefer the native helm commands generally more featured (more than one action, allows marking candidates, better display etc…).

Quick Try

To try Helm with a default configurations in a minimal Emacs, run the provided emacs-helm.sh script in Helm’s installation directory. If installed through the Emacs package manager,

~/.emacs.d/elpa/helm-<VERSION>/emacs-helm.sh

emacs-helm.sh should also be used when reporting bugs.

Note: for convenience, consider creating a symlink of emacs-helm.sh to e.g ~/bin.

Helm Completion v.s. Emacs Completion

Differences between the two often trip up new users.

Emacs completion is based on the minibuffer. Helm completion is based on the completion window.

In default Emacs, interactivity happens in the minibuffer.

  • Typing new characters filters candidates in the minibuffer.
    • <tab> may try to complete the typed characters with a valid candidate.
  • Hitting RET selects the current candidate from the minibuffer.

In Helm, interactivity happens in the completion window, not the minibuffer

  • Typing new characters filters candidates in the completion window.
    • Type until the desired candidate is highlighted, or navigate to it using C-n.
  • Hitting RET selects the currently highlighted item in the completion window.

Helm interaction model

Helm’s interactivity makes the <tab> key redundant for completion because the selection candidates are already made visible in the Helm completion window. So, tab completion is not supported. In Helm, <tab> is used to view available actions to be taken on a candidate.

Because the <tab> key is so ingrained in the muscle memory of long-time Emacs users, transition to Helm’s interactive model requires:

  • A conscious visual adjustment to look at the completion window, and
  • A conscious mental adjustment to avoid using the <tab> key for completion and go straight to <RET> key to select a candidate. Helm’s approach to completion provides better visual cues, takes fewer keystrokes, and is much faster.

General Helm Commands

Helm’s functionality needs only a few general key bindings as shown below. These are also documented in the mode line.

  • <tab> or C-i lists available actions
  • C-j or C-z invokes the persistent action
  • M-SPC or C-SPC marks a candidate
  • C-h m displays the embeded help in an org buffer without quitting helm session.
  • RET runs the first action of action list

Yanking text

Yank symbol at point from helm-current-buffer (i.e. buffer where a helm command was invoked):

M-n copies symbol at point to minibuffer

C-w appends word next to point to the minibuffer and advance to next word, hitting C-_ undo last insertion and rewind yank point in helm-current-buffer

Preconfigured Helm Commands

  • helm-command-prefix-key is the prefix for the preconfigured helm menu.
  • C-x c is the default key binding for helm-command-prefix-key.
  • helm-M-x and then type “helm” to discover Helm commands.
    • This is the same as running helm-command-prefix-key followed by M-x.
  • The Helm > All commands menu item is another way to discover helm commands.
    • It runs helm-execute-helm-command.
  • helm-command-prefix-key followed by any regular Emacs key invokes the Helm version of the same command.
    • E.g. helm-M-x for M-x.

To run the helm version of a command with a key binding, set it in your init file as follows:

(global-set-key (kbd "M-x") 'helm-M-x)

Show Helm Commands

  • C-h m shows Helm commands and currently active key bindings.

Browse Other Tools

  • Invoke M-x, then type “helm” to browse other Helm tools.

helm-mode

helm-mode enables Helm completion globally for any Emacs command using completing-read or read-file-name.

helm-mode completes with completion-at-point and implements completion-in-region-function for completing-read-multiple for Emacs 24.4 and later.

Helm provides generic functions for completions to replace tab-completion in Emacs with no loss of functionality. To use Helm’s generic functions, first set them in your init file, e.g.:

(global-set-key (kbd "M-x") #'helm-M-x)
(global-set-key (kbd "C-x r b") #'helm-filtered-bookmarks)
(global-set-key (kbd "C-x C-f") #'helm-find-files)

Then enable helm-mode with:

(helm-mode 1)

Or, enable helm-mode interactively with M-x helm-mode.

Customize helm-mode

To customize the completion interface or disable completion for specific commands in helm-mode, edit helm-completing-read-handlers-alist. See C-h v helm-completing-read-handlers-alist for details.

Use helm-mode and ido-mode

To use Ido for some commands and Helm for others, do not enable ido-mode. Instead, customize helm-completing-read-handlers-alist to specify which command uses Ido.

For example, suppose we want find-file-read-only to use Ido and find-file to use Helm. Then:

  1. In your init file, turn on helm-mode.
  2. In the helm-mode customize group, add a key to helm-completing-read-handlers-alist for find-file-read-only with value ido, i.e.
(find-file-read-only . ido)

With helm-mode active, to use Emacs default completion instead of either Helm or Ido, use nil for the key value:

(find-alternate-file . nil)

Other Useful Extensions

MELPA and other repositories have many useful extensions, some of which are redundant as Helm already provides them. Review if they already exist as part of the default Helm package before downloading new extensions.

Helm With Other Emacs Extensions

linum-relative

(helm-linum-relative-mode 1) enables linum-relative in Helm. Helm buffers then display line numbered candidates before and after the current candidate (highlighted line). C-x <n> jumps to n lines before, before, and C-c <n> jumps to n lines after, the current candidate.

Helm Workflow for Files, Directories and Buffers

The new Helm workflow uses fewer buffers. Whereas the old workflow opened many Dired buffers stacked in the workspace, the new approach uses virtual Dired buffers without cluttering the buffer list with many Dired buffers. The decluttering of buffers also helps with running helm-locate without conflicts; there’s also less need to resort to other workarounds, such as running helm-multi-files.

The new approach uses helm-find-files as the starting point, never opens Dired buffers yet provides easy access to common Helm commands, such as grep, locate, find, etc. These Helm commands, moreover, are not limited to the current directory because Helm now allows marking files in other directories before running the commands.

Other quick jumping off features of helm-find-files:

  • C-x C-d (helm-browse-project) shows buffers and files in the project.
  • C-c C-d with prefix argument shows files in this directory and its subdirectories recursively.

When using helm-ls-git and helm-ls-hg, files under version control have a corresponding backend indicator.

  • C-x C-b to switch back to the resumed Helm sources.
  • M-p to access history of helm-find-files
  • C-c h to access the full history of files (file-name-history)
  • C-x C-f switches back to helm-find-files

Useful links

Contributing to the Wiki

  1. Prefer using Org mode for Wiki pages.
  2. Install the toc-org package to automatically generate tables of contents.
  3. Edit the Wiki.
  4. Before saving, run toc-org-insert-toc.
    • Consider adding something like the following to before-save-hook to do this automatically:
(defun *-org-insert-toc ()
  "Create table of contents (TOC) if current buffer is in
`org-mode'."
  (when (= major-mode 'org-mode)
    toc-org-insert-toc))
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.