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


Maintainance of Helm is a Lot of work I have done freely since 2011.
As it demands lots of my time it gets increasingly difficult
maintaining it without financial help.
Thanks to all the people that are helping or have helped Helm development,
but they are actually too few to continue serenely.
By the way, after the release of version 3.0 I will have to stop
developing Helm seriously until I get enough financial support,
only providing a minimal bugfix maintenance.
Thanks for your understanding
If you feel Helm is making your daily work easier,
please consider making a donation.
Thank you! — Thierry Volpiatto
Donate with Paypal    Donate monthly using Patreon   

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.

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.

Requirements

Helm requires Emacs-24.4 or later versions.

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

Getting Started

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

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

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 guide and 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

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

Known issues

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

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