Helm Wiki

Table of Contents

Helm Wiki

— The Detailed Node Listing —

Installation, Upgrade, and Configuration

Helm Completion v.s. Emacs Completion

General Helm Commands

Helm Mode

Customize helm-mode

Helm With Other Emacs Extensions

How to report Helm Bugs

Confirming bugs

Reporting bugs

1 Requirements

Helm 3.6.2 and later require

• ‘Emacs’ version >= 25.1
• ‘emacs-async’¹
• ‘popup-el’²

2 Download

Home Page

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

Git Url

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

git@github.com:emacs-helm/helm.git

Tagged Releases

https://github.com/emacs-helm/helm/tags

3 Installation, Upgrade, and Configuration

3.1 Minimal setup using ‘straight.el’

‘straight.el’³

Add this to your init file,

(straight-use-package 'helm)

or

# :straight t # :config # […])

(use-package helm :straight t)

For further information, see ‘straight.el’’s user manual.

To upgrade ‘helm’, do M-x straight-pull-package and restart Emacs. ‘straight.el’ will rebuild helm for you.

3.2 Minimal setup using source

1. Install the pre-requisites

   Install ‘emacs-async’⁴ and ‘popup-el’⁵. Ensure that they are available in load-path.

2. Download, compile and install the sources

   If you are using ‘git’,

   git clone https://github.com/emacs-helm/helm
   cd helm
   make
   sudo make install
   

   If you have a tarball⁶,

   wget https://github.com/emacs-helm/helm/archive/refs/tags/v3.7.1.tar.gz
   tar zxvf v3.7.1.tar.gz
   cd helm-3.7.1/
   make
   sudo make install
   

Above steps assume that you have installed ‘emacs-async’ is in a standard location. If this is not the case, you need to tell ‘make’ program where it is available using ‘EMACSLOADPATH’⁷.

git clone https://github.com/emacs-helm/helm
cd helm
EMACSLOADPATH="/path/to/emacs-async:" make
make
sudo make install

Above steps

• installs ‘helm’ in ‘/usr/local/share/emacs/site-lisp/helm/’
• creates an executable called ‘/usr/local/bin/helm’. This file is in fact a symbolic link to to the script ‘emacs-helm.sh’.

If you want to install ‘helm’ in a path other than ‘/usr/local/’, pass that target path through a ‘PREFIX’ variable.

Add the one of the following to your init file,

(add-to-list 'load-path "/path/to/helm/directory")
(require 'helm-config)

or

(add-to-list 'load-path "/path/to/helm/directory")
(use-package helm :config (require 'helm-config))

and restart Emacs.

The library ‘helm-config’ loads ‘helm-autoloads.el’. This is essential for having a working install of ‘helm’.

3.3 Minimal setup using the Package Manager

Helm is available on MELPA.⁸

Release version of Helm is available in the stable repository while development version is available in the other repo.

Assuming that you have setup package-archives to include the MELPA, you can install Helm with M-x package-install RET helm RET.

To upgrade ‘Helm’, use helm-list-elisp-packages. This command is the Helm equivalent of Emacs’ ‘list-packages’. Using helm-list-elisp-packages, ensures that ‘helm’ is compiled in a clean environment.⁹

4 Introduction

People often think helm is just something like ido((Ido)Top) 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.

Helm is divided in two distinct categories of commands,

helm natives commands

these commands are a fresh implementation of an existing Emacs command and enhance them in useful ways.

helmized commands

these 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…).

5 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.^{10 11 12}

In standard 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. Keep typing until the desired candidate is highlighted, or navigate to it using C-n.
• Hitting RET selects the currently highlighted item in the completion window.

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

6 General Helm Commands

Figure: A typical helm-M-x with

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 (helm-select-action)

lists available actions

C-j or C-z (helm-execute-persistent-action)

invokes the persistent action

M-SPC (helm-toggle-visible-mark-backward) or C-SPC (helm-toggle-visible-mark-forward) or C-@ (helm-toggle-visible-mark)

marks a candidate

C-h m (helm-help)

displays the embeded help in an org buffer without quitting helm session.

RET

runs the first action of action list

6.1 Yanking text

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

C-w (helm-yank-text-at-point)

Append word next to point to the minibuffer and advance to next word

(helm-yank-text-at-point ARG)

Yank text at point in ‘helm-current-buffer’ into minibuffer.

C-_ (helm-undo-yank-text-at-point)

Undo last insertion and rewind yank point in helm-current-buffer

Undo last entry added by ‘helm-yank-text-at-point’.

7 Preconfigured Helm Commands

Invoke M-x helm-M-x RET and type ‘helm’ to discover Helm commands. The ‘Menu Bar -> Helm’ menu item is another way to discover helm commands.

helm-command-prefix-key

Standard Value: “C-x c”

The key ‘helm-command-prefix’ is bound to in the global map.

helm-minibuffer-history-key

Standard Value: “C-r”

The key ‘helm-minibuffer-history’ is bound to in minibuffer local maps.

helm-command-prefix-key (default value C-x c) is the prefix for the preconfigured helm menu.

helm-command-prefix-key followed by any regular Emacs key invokes the Helm version of the same command.

For example,

• C-x c M-x runs the command helm-M-x, which is the helm version of M-x (execute-extended-command).
• C-x c C-x C-f runs the command helm-find-files, which is the helm version of C-x C-f (find-file).

To run the helm version of a command with a key binding, but without also typing C-x c) (helm-command-prefix-key), add the following to your init file.

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

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

helm-mode

(helm-mode &optional ARG)

Toggle generic helm completion.

If called interactively, toggle ‘Helm mode’. If the prefix argument is positive, enable the mode, and if it is zero or negative, disable the mode.

If called from Lisp, toggle the mode if ARG is ‘toggle’. Enable the mode if ARG is nil, omitted, or is a positive number. Disable the mode if ARG is a negative number.

The mode’s hook is called both when the mode is enabled and when it is disabled.

All functions in Emacs that use ‘completing-read’, ‘read-file-name’, ‘completion-in-region’ and friends will use helm interface when this mode is turned on.

However you can modify this behavior for functions of your choice with ‘helm-completing-read-handlers-alist’.

Called with a positive arg, turn on unconditionally, with a negative arg turn off. You can toggle it with M-x ‘helm-mode’.

About ‘ido-mode’: DO NOT enable ‘ido-everywhere’ when using ‘helm-mode’. Instead of using ‘ido-mode’, add the commands where you want to use ido to ‘helm-completing-read-handlers-alist’ with ‘ido’ as value.

Note: This mode is incompatible with Emacs23.

8.1 Customize helm-mode

helm-completing-read-handlers-alist

Completing read functions for specific Emacs commands.

By default ‘helm-mode’ use ‘helm-completing-read-default-handler’ to provide helm completion in each ‘completing-read’ or ‘read-file-name’ found, but other functions can be specified here for specific commands. This also allows disabling helm completion for some commands when needed.

Each entry is a cons cell like (EMACS_COMMAND . COMPLETING-READ_HANDLER) where key and value are symbols.

Each key is an Emacs command that use originaly ‘completing-read’.

Each value maybe a helm function that takes same arguments as ‘completing-read’ plus NAME and BUFFER, where NAME is the name of the new helm source and BUFFER the name of the buffer we will use, but it can be also a function not using helm, in this case the function should take the same args as ‘completing-read’ and not be prefixed by “helm-”.

‘helm’ will use the name of the command calling ‘completing-read’ as NAME and BUFFER will be computed as well with NAME but prefixed with “*helm-mode-”.

This function prefix name must start by “helm-” when it uses helm, otherwise ‘helm’ assumes the function is not a helm function and expects the same args as ‘completing-read’, this allows you to define a handler not using helm completion.

Example:

(defun foo/test () (interactive) (message “%S” (completing-read “test: ” ’(a b c d e))))

(defun helm-foo/test-completing-read-handler (prompt collection predicate require-match initial-input hist def inherit-input-method name buffer) (helm-comp-read prompt collection :marked-candidates t :name name :buffer buffer))

(add-to-list ’helm-completing-read-handlers-alist ’(foo/test . helm-foo/test-completing-read-handler))

We want here to make the regular ‘completing-read’ in ‘foo/test’ return a list of candidate(s) instead of a single candidate.

Note that this function will be reused for ALL the ‘completing-read’ of this command, so it should handle all cases. E.g., if first ‘completing-read’ completes against symbols and second ‘completing-read’ should handle only buffer, your specialized function should handle both.

If the value of an entry is nil completion will fall back to Emacs vanilla behaviour. Example:

If you want to disable helm completion for ‘describe-function’, use:

(describe-function . nil)

Ido is also supported, you can use ‘ido-completing-read’ and ‘ido-read-file-name’ as value of an entry or just ’ido. Example: Enable ido completion for ‘find-file’:

(find-file . ido)

same as

(find-file . ido-read-file-name)

Note that you don’t need to enable ‘ido-mode’ for this to work, see ‘helm-mode’ documentation.

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.

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

9 Helm With Other Emacs Extensions

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

10 Helm Workflow for Files, Directories and Buffers

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

11 Quick Try with ‘emacs-helm.sh’

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: If you have installed from Melpa, for convenience, consider creating a symlink of ‘emacs-helm.sh’ to e.g ‘~/bin’, if you have installed from source (make && sudo make install) a symlink named ‘helm’ have already been created.

Note: For people using a non standard Elpa directory emacs-helm.sh may fail because it doesn’t find its dependency (emacs-async), here’s how you can do:

cd /your/path/to/helm
make # If not already done.
EMACSLOADPATH="../emacs-async:" ./emacs-helm.sh

But normally ‘emacs-helm.sh’ should work out of the box with installations of emacs-async= done with package.el, straight.el or from source with the Makefile.

12 How to report Helm Bugs

12.1 Confirming bugs

To confirm that a bug is, in fact, a Helm problem, it is important to replicate the behavior with a minimal Emacs configuration. This precludes the possibility that the bug is caused by factors outside of Helm.

The easiest and recommended way to do so is through the ‘emacs-helm.sh’ script.

12.1.1 ‘emacs-helm.sh’

If your system supports it, you should run the ‘emacs-helm.sh’ script to start an Emacs instance with minimal, Helm-specific configuration.

This is useful for debugging, and easier than starting Emacs with ‘emacs -Q’ and configuring Helm from scratch.

If Helm is installed via MELPA, the ‘emacs-helm.sh’ script should be located at ‘~/.emacs.d/elpa/helm-<version>/emacs-helm.sh’.

Of course you have to cd to your helm directory and run the script from there, an alternative is symlinking it to somewhere in your ‘PATH’ e.g. “~/bin” (See note at bottom for those that have installed from source with ‘make’).

You can use the -h argument for help:

$ helm -h
Usage: helm [-P} Emacs path [-h} help [--] EMACS ARGS

If your emacs binary is not in a standard place i.e. “emacs”, you can specify the path with “-P”.

Note: If you have installed Helm from Git and used ‘make && sudo make install’ you can run directly ‘helm’ at command line from any place i.e. no need to cd to helm directory.

12.1.2 ‘emacs -Q’

If you cannot run the ‘emacs-helm.sh’ script, be sure to reproduce the problem with ‘emacs -Q’, then installing Helm as described in the Install section.

12.2 Reporting bugs

To report a bug, open an issue. Be sure that you’ve confirmed the bug as described in the previous section, and include relevant information for the maintainer to identify the bug.

12.2.1 Version info

When reporting bugs, it is important to include the Helm version number, which can be found in the helm-pkg.el file.

13 Useful links

• Helm on GitHub
• Tuhdo’s Helm tutorial
• Helm mailing list

14 Main Index

15 Key Index

16 Command and Function Index

17 Variable Index

This is not a complete index of variables and faces, only the ones that are mentioned in the manual. For a more complete list, use M-x org-customize and then click yourself through the tree.