Skip to content

Home

Thierry Volpiatto edited this page · 111 revisions

Welcome to the Emacs-helm wiki!

Table of Contents

Helm wiki maintainer instructions

  1. Checkout wiki repo at https://github.com/emacs-helm/helm.wiki.git
  2. Get markdown-toc package
  3. Edit wiki.
  4. Run M-x markdown-toc-generate-toc inside its section

Install

First get the files from the git repo:

The Helm git repo is at: https://github.com/emacs-helm/helm There, you will find tarballs of differents versions in the Tags section.

To get it with git:

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

Once you have the helm directory, cd into it and run make. Edit your 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:

./emacs-helm.sh

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 minibuffer completion is subtly different to Helm, and many (1, 2, 3) new comers struggle with the difference.

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 you hit <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 with <C-n> and hit <enter> to select it.

The key implications of the helm "mental model"

  1. <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.
  2. Therefore <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 <tab> do expansion.

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

    TAB
    
  • Use persistent actions with

    C-z
    
  • Mark candidate with

    M-<SPACE>
    

So there are three bindings to remember and they are also documented in mode-line. For more, hitting

    C-h m

while in helm session will show you all other bindings.

Yanking text

To yank the symbol at point from helm-current-buffer (i.e. buffer where a helm command originated) to minibuffer:

    M-n

To append the next word at point from helm-current-buffer to minibuffer:

    C-w

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 prefixed with helm-command-prefix-key (default to C-x c).

To discover more helm commands run helm all commands (helm-execute-helm-command) from the menu. Or run helm-M-x (helm-command-prefix-key M-x) and type helm.

Typing helm-command-prefix-key before a normal command like M-x 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 convenient like M-x. To replace the Emacs original keybinding, paste this in your init.el:

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

Special commands

Not complete.

C-h m will show you all commands available.

Other tools

In addition to the above, you will find a bunch of powerful tools that come with helm, just browse the available helm commands with M-x helm-.

Not complete.

Helm mode

helm-mode will enable helm completion in all Emacs commands using completing-read or read-file-name.

Starting with emacs-24.4 helm-mode provide also completion with completion-at-point and completing-read-multiple by implementing a helm completion-in-region-function.

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 execute-extended-command vs helm-M-x, find-file vs helm-find-files etc... 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.

e.g:

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

etc...

To use it:

M-x helm-mode

Turn it on in init.el with:

(helm-mode 1)

Customize how helm-mode behave

You can disable or change the completion interface you want to use for a specific command by customizing helm-completing-read-handlers-alist.

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 ido-mode, instead customize helm-completing-read-handlers-alist; For example, you want ido-mode for find-file-read-only and helm-mode for find-file: 1) In your config you turn on helm-mode. 2) In customize-group helm-mode add to helm-completing-read-handlers-alist 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) is using helm-mode.

Now you want find-alternate-file to not use ido and to not use helm, only the vanilla emacs completion: Add an entry to helm-completing-read-handlers-alist like this:

 (find-alternate-file . nil)

Usefuls extensions

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

linum-relative

You can use linum-relative in helm by enabling it helm-linum-relative-mode :

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. From 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. Always from 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 helm-find-files using C-x C-f. 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 with C-x b. The history of your directories from helm-find-files is accessed with M-p and the full history of files (file-name-history) is accessed via C-c h.

Usefuls links

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

!REF

Something went wrong with that request. Please try again.