Clone this wiki locally
Welcome to the Emacs-helm wiki!
Table of Contents
- Helm wiki maintainer instructions
- Emacs completion vs Helm
- General helm commands
- Overview of preconfigured helm commands
- Special commands
- Other tools
- Helm mode
- Usefuls extensions
- Interaction of helm with other emacs extensions
- The Helm workflow with files, directories and buffers
- Usefuls links
Helm wiki maintainer instructions
- Checkout wiki repo at https://github.com/emacs-helm/helm.wiki.git
- Get markdown-toc package
- Edit wiki.
- Run M-x
markdown-toc-generate-tocinside its section
First get the files from the git repo:
The Helm git repo is at:
There, you will find tarballs of differents versions in the
To get it with git:
git clone https://github.com/emacs-helm/helm
Once you have the helm directory,
cd into it and run
init.el file and add:
(add-to-list 'load-path "/path/to/helm/directory") (require 'helm-config)
For a quick try, you can also run the shell script provided with helm if your system support it:
NOTE: If you install Helm in a different way using your own autoloads and personal configuration, be sure to know and understand what you are doing, otherwise expect diverse bugs and failures. You are warned!
Emacs completion vs Helm
Emacs default completion is minibuffer centric
Emacs helps you narrow down your selection by transforming your minibuffer
input when you hit
<tab>. And then your give it some more detail and hit
<tab> again, until finally,the minibuffer contains the desired input and
<enter> to select it.
Helm is completion window centric
In Helm, you don't pay attention to the minibuffer. Instead, you look at the completion window and the currently highlighted item.
You narrow the list shown in the completion window by providing more input.
When the item is close enough to the current highlight, you navigate to it
<C-n> and hit
<enter> to select it.
The key implications of the helm "mental model"
<tab>is not needed to expand the minibuffer input.
- The minibuffer need not ever contain the selection you want, so there is no point in transforming it.
<tab>is used to select a different action in Helm.
- In Emacs completion, there is only one action available, but Helm offers many actions.
- This is a feature. Please don't ask how to make
General helm commands
Helm needs you to remember only a few binding unlike all other Emacs applications. Thus, all bindings are auto documented.
By default, Helm shows you the most useful bindings in the mode-line. You will see some more specific commands in the header of the helm buffer.
So when helm starts, you have to remember:
Access to action menu with
Use persistent actions with
Mark candidate with
So there are three bindings to remember and they are also documented in mode-line. For more, hitting
while in helm session will show you all other bindings.
To yank the symbol at point from
helm-current-buffer (i.e. buffer where a
helm command originated) to minibuffer:
To append the next word at point from
helm-current-buffer to minibuffer:
Overview of preconfigured helm commands
To start with helm, a set of commands have
been set for you in the helm menu. The bindings of all these commands are
helm-command-prefix-key (default to
To discover more helm commands run
helm all commands
(helm-execute-helm-command) from the menu. Or run helm-M-x (
M-x) and type helm.
helm-command-prefix-key before a normal command like
will run the helm version of that command:
helm-M-x. If you prefer
the helm version of a command, you should bind it to something more
M-x. To replace the Emacs original keybinding, paste
this in your init.el:
(global-set-key (kbd "M-x") 'helm-M-x)
C-h m will show you all commands available.
In addition to the above, you will find a bunch of powerful tools that
come with helm, just browse the available helm commands with
helm-mode will enable
helm completion in all Emacs commands using
Starting with emacs-24.4
helm-mode provide also completion with
completing-read-multiple by implementing a helm
What helm is providing for those native emacs commands is a generic helm function providing
exactly the same feature emacs provides but with helm completion instead of the usual TAB completion
provided by emacs. This generic helm completion have nothing to do with their counterparts provided
natively by helm, e.g
even if at first they may look similar. You have better time using and bounding these native helm commands
when they are provided instead of using the generic ones.
(global-set-key (kbd "M-x") 'undefined) (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)
To use it:
Turn it on in
Customize how helm-mode behave
You can disable or change the completion interface you want to use for a specific command by
See C-h v
helm-completing-read-handlers-alist for more infos.
Use helm-mode and ido-mode
If you like ido for some commands and helm for other commands, you should not enable
helm-completing-read-handlers-alist; For example, you want
1) In your config you turn on
2) In customize-group
helm-mode add to
find-file-read-only as key and
ido as value.
In elisp it looks like this:
(find-file-read-only . ido)
That's it, now
find-file-read-only is now using ido an
find-file (because you did nothing)
Now you want
find-alternate-file to not use ido and to not use helm, only the vanilla emacs
Add an entry to
helm-completing-read-handlers-alist like this:
(find-alternate-file . nil)
You will find many helm extensions available from MELPA, many are providing features already implemented in helm itself, so before installing helm extensions, be sure feature is not already implemented in helm. Helm extensions provided in emacs-helm organization are generally well maintained and follow the helm development.
Interaction of helm with other emacs extensions
You can use linum-relative in helm by enabling it
Once the mode enabled with
(helm-linum-relative-mode 1) you will see the relative candidates numbers
in your helm buffers, you can jump to the nine numbered candidates before or after current selection
(the line highlighted in your helm buffer) by using
C-x <n> for the ones before selection and
C-c <n> for the ones after.
The Helm workflow with files, directories and buffers
Old helm users were used to throw many sources in one buffer (e.g helm-mini, helm-for-files)
and just type in pattern to find their files, and use dired to open their directories.
This approach is like in emacs based on default-directory and current-buffer and limit you to this
zone, thus it leave tons of dired buffers open.
Also one of the thing people like which is particularly inefficient is running helm-locate at the same
time with all others source, an alternative of this have been done with
helm-multi-files which prevent
running locate at the same time with all other sources, but it is not the best you can do with helm.
The new approach is using
helm-find-files as a starting point and never open a dired buffer.
You can see
helm-find-files like a virtual dired buffer that you can use anywhere.
helm-find-files, you have access to many other helm commands (e.g grep, locate, find, etc...) and
you are not limited to current directory, you can for example mark several files from different directories and
run helm grep on them.
helm-find-files you can run
C-x C-d (
helm-browse-project) which allow you to see
all buffers under this directory and all files in project.
If you use helm-ls-git and helm-ls-hg
the files under this directory will be shown using the corresponding backend, otherwise, if the directory is not
under version controls you will have to give a prefix arg the first time you run
C-c C-d to see all files under
this directory (recursively).
At any time, you can switch back to
During this session you can also switch back to the resumed helm sources you ran previously using
C-x C-b, or the very last
The history of your directories from
helm-find-files is accessed with
M-p and the full history of files (
You can have infos about helm on Github. https://github.com/emacs-helm/helm
And a very detailed tutorial about the possibilities of Helm by the user Tuhdo: http://tuhdo.github.io/helm-intro.html
You can ask on the helm mailing-list by subscribing at: https://groups.google.com/group/emacs-helm?hl=en
Or at gmane: gmane.emacs.helm.user