License GPL 3 MELPA MELPA Stable

Emacs-helm

Emacs-helm

Helm is an Emacs framework for incremental completions and narrowing selections. It helps to rapidly complete file names, buffer names, or any other Emacs interactions requiring selecting an item from a list of possible choices. Helm is a fork of anything.el, which was originally written by Tamas Patrovic and can be considered to be its successor. Helm cleans the legacy code that is leaner, modular, and unchained from constraints of backward compatibility.

Helm wiki | FAQ

Table of Contents

Introduction

Helm is an Emacs framework for incremental completions and narrowing selections. It helps to rapidly complete file names, buffer names, or any other Emacs interactions requiring selecting an item from a list of possible choices.

Helm is a fork of anything.el, which was originally written by Tamas Patrovic and can be considered to be its successor. Helm cleans the legacy code that is leaner, modular, and unchained from constraints of backward compatibility.

helm-grep-ag

Features

In addition of its framework where you can build your own Helm applications, Helm provides preconfigured commands to browse and search incrementally in files, buffers, bookmarks etc… and much more. Helm allows displaying different sources in same session. Helm displays its candidates in a window or a frame, keeping the minibuffer for user input. Helm provides a full set of actions for each of its sources, each action apply on a single candidate or a set of marked candidates.

Note: You will find many helm extensions providing diverse features sometimes already implemented in Helm, prefer generally the ones that are natively in Helm, e.g. Helm support natively most grep implementations as backend (ack, ag, rg), no need to install 3rd party packages for this, same for managing projects etc…

Alternatives

There are several alternatives to Helm nowaday, they are all providing incremental completion but they lack all the Helm features due to their wrong implementation abusing minibuffer.

Requirements

Helm requires Emacs-25.1 or later versions.

Helm installs async and popup-el package as dependencies when Helm is installed using MELPA.

Getting Started

Install from Straight

See Install from straight package manager

Quick install from git

See Install Helm from Git

NOTE: Installing helm using git and make is the safest way.

Install from Emacs packaging system

See Install Helm from Melpa

NOTE: This is not the recommended way to install packages.

Installing just the helm-core package

helm-core package is available on MELPA for third party packages that depend on helm libraries. These packages should require helm as follows:

 (require 'helm)

Requiring helm builds and runs helm code necessary for multiple regexp and fuzzy matching. See helm wiki for details.

Warning about alternate installation methods

Installation methods that circumvent helm-config are known to fail if the careful safeguards are not implemented in the hacks.

Configuration

For minimal helm configuration, run the start-up script ./emacs-helm.sh and then see the file /tmp/helm-cfg.el.

The full configuration I (the helm maintainer) use is here.

Also see helm customizable variables with the customize interface.

Enabling helm-mode will enable helm for many features of emacs requiring completions, see below how to enable helm-mode.

Basic usage

M-x helm-M-x RET helm- lists helm commands ready for narrowing and selecting.

To bind to M-x:

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

In any helm session, as soon there is candidates in the helm buffer

C-h m pops an org buffer with detailed documentation about current command and more generalized infos about helm.

Use it with no moderation!

Use these embedded Info screens first before reporting bugs.

M-x helm-mode to enable helm completion for common Emacs commands. Note that the helm functionality enabled through helm-mode comes from a generic implementation and does not include all helm features available through equivalent helm-specific commands. See FAQ about M-x and C-x C-f.

To make helm-mode start with Emacs init file:

(helm-mode 1)

To discover basic helm commands, look at helm menu item in Emacs menu.

Another way to discover helm commands: run the shell script: ./emacs-helm.sh from helm directory and then look in the scratch buffer. emacs-helm.sh accepts emacs command line options. emacs-helm.sh -h opens an Info screen with more details.

Note: When helm is installed with “make install” you will have a shell command named helm that you can run from any places i.e. not only the helm directory

See https://github.com/emacs-helm/helm/wiki#quick-try-with-emacs-helmsh

Advanced usage

Helm contains many features, some of which are easier to follow visually. Here is a demo of helm-buffers-list used with helm-moccur. Demo starts with Eval: START in the minibuffer.

helm-buffers-list

With more pattern matching, candidates are narrowed down from the initial 253 buffers to 12 as shown in the modeline.

Helm Wiki provide additional details.

Matching methods

Helm support by default multi pattern matching, it is the standard way of matching in helm. E.g You can use a pattern like “foo bar” to match a line containing “foo” and “bar” or “bar” and “foo”. Each pattern can be a regexp.

In addition helm support fuzzy matching.

Creating custom helm sources

An example:


(helm :sources (helm-build-sync-source "test"
                 :candidates '(foo foa fob bar baz)
                 :fuzzy-match t)
      :buffer "*helm test*")

The candidates list may be replaced by a function that produces a list. See (helm wiki) for details.

Helm Applications

These are popular applications developed using helm completion and narrowing framework. They are available for individual installs through the Emacs package manager. This list is not exhaustive.

Recommended Helm extensions

Normally all Helm modules coming from Emacs-helm organisation are safe to use otherwise it is mentioned in their README if they are broken or unmaintained. Here some of them I am using:

Warning Helm development has sparked quite a few extensions, many of which duplicate features already included in helm. Some of these packages (about 20 at last count in the MELPA repository) are either deprecated or unmaintained. Moreover, many remain out-of-sync with helm core development cycles causing incompatibilities. To avoid helm problems or unstable emacs, please look for comparable features within helm and emacs-helm before installing such extensions.

Other emacs extensions recommended with helm

External programs recommended with helm

Known issues

The Helm project has a current unresolved issue list. Please feel free to fix any of them; send a pull request.

Most issues come from a wrong configuration or a use of Helm modified externally by third party package e.g. Spacemacs. Some other Helm packages that are no more maintained (or badly maintained) and use deprecated Helm code will clash also with recent Helm be aware.

Contributors

The Helm project maintains a list of contributors.

Bugs & Improvements

The Helm Team welcomes bug reports and suggestions. Note that not all bugs when using Helm are due to Helm. Because of the way Helm interacts with many Emacs features, bugs may be related to Emacs itself.

One way to ascertain that the bugs are helm-related, recreate the error either by using Emacs -Q or by running the included package script ./emacs-helm.sh located in the helm directory.

Helm comes now with a template for filling bugs, when reporting issues, be sure to fill all sections and to run helm from a minimal install as described above to reproduce your bug.

Getting help

Helm Wiki and emacs-helm Google group are two readily available locations.

Cheers,
The Helm Team