-
-
Notifications
You must be signed in to change notification settings - Fork 389
Home
- Requirements
- Install
- Upgrade or recompile
- Configure
- General concept
- Quick Try with emacs-helm.sh
- Helm Completion v.s. Emacs Completion
- General Helm Commands
- Preconfigured Helm Commands
- Show Helm Commands
- Browse Other Tools
- ~helm-mode~
- Other Useful Extensions
- Helm With Other Emacs Extensions
- Helm Workflow for Files, Directories and Buffers
- Basic scripting with emacs-helm.sh
- Useful links
- Contributing to the Wiki
Helm require an emacs version >= 25.1 starting from version 3.6.2. Helm uses few dependencies, actually only emacs-async (mandatory) and wfnames but if you install from Melpa you should not care about this. For a better experience, it is good to install all-the-icons and svg-lib but it is not mandatory. Also it is a good idea to install a good grep program like RipGrep
Add this to your init file (straight-use-package 'helm)
,
or
(use-package helm
:straight t
:config
[...])
see Straight getting started for more info.
Helm needs emacs-async and wfnames (not mandatory) as dependencies,
install them somewhere in your load-path
.
NOTE: When installing emacs-async from sources you should install it
using make
and make install
to ensure helm will find it when running
make, otherwise you will have to specify its location from the command line, see below.
To install Helm, get the files from the helm git repo (see the
tagged releases for older versions) with git
(see command below)
or by downloading an archive and decompressing it.
git clone https://github.com/emacs-helm/helm
Then go to the resulting Helm directory and run
make
and
sudo make install
NOTE:
Since helm version 2.7.0, helm wont compile with just make
if you
have installed emacs-async in a non standard location, in that case
you will have to specify where emacs-async live on the command line,
with the EMACSLOADPATH
environment variable.
So after downloading, go to the resulting Helm directory and run
EMACSLOADPATH="/path/to/emacs-async:" make
Don’t forget the final “:” to not override other load-paths and use an
absolute path not abbreviated, i.e /home/you/foo/bar:
and not
~/foo/bar:
to specify EMACSLOADPATH
.
When installing from source with make && sudo make install, helm files are installed in “${PREFIX}share/emacs/site-lisp/helm/” where PREFIX is ”usr/local” by default, if your emacs is installed somewhere else specify PREFIX on command line.
As a benefit of installing from source, make install creates a symlink
called helm
in “${PREFIX}bin which allows you to call the script
emacs-helm.sh from anywhere i.e. no need to cd in Helm directory.
NOTE: make install will NOT work on Windows system, but you can move
your helm directory to your load-path
e.g. /site-lisp and run make
there.
Helm is available on 3 major package.el
community-maintained repos:
MELPA, NonGnu and MELPA Stable. For MELPA, Follow the instructions to set up the repository.
Install Helm with M-x package-install RET helm RET
.
Note: always restart Emacs after reinstalling Helm (or other packages) for updates to take effect.
The only thing you have to do is to upgrade from package manager. Be sure to RESTART Emacs once upgraded. You can use M-x helm-packages which is easy to use, asynchronous etc…
Helm upgrades from MELPA encountered errors because of the way the Emacs package manager fetches and compiles updates for existing packages.
To get around these errors, Helm has emacs-async as a dependency. emacs-async
forces compilation in a clean environment, which resolves the compilation errors.
You are strongly advised to NOT disable
async-bytecomp-package-mode
and to not remove Helm from
async-bytecomp-allowed-packages
. Even better is to use in your
config (setq async-bytecomp-allowed-packages '(all))
, this to compile
all packages async for safety.
When some changes are made in Helm-core and those changes are used in Helm, package.el may install Helm before Helm-core which may create errors depending on changes on Helm-core e.g. New macro, renaming function or macro etc… In this case you will have a better time uninstalling all (Helm+Helm-core), restarting Emacs and reinstalling Helm. Installing/upgrading from source doesn’t suffer from this problem.
Use make
or make && sudo make install
and RESTART Emacs.
Once you have called straight-pull-package
of straight-pull-all
,
restart Emacs, straight will rebuild helm for you.
Note: In the past we had a file called “helm-config.el” that was needed for installation from source only (most people were requiring it with an installation from package which was unuseful) the file doesn’t exists anymore, therefore if you try to require it you will have an error.
You should have nothing to do, most commands should be autoloaded. However you will not have the global bindings enabled until you require helm with either require or use-package.
Not much to do either, you need a straight or use-package declaration:
(straight-use-package 'helm)
Or
(use-package helm :straight t)
Ensure the emacs-async package is in load-path
:
(add-to-list 'load-path "/path/to/emacs-async/directory")
When installed from source you have to load the helm-autoloads.el file
generated by Make, (require 'helm-autoloads)
is doing that for you.
add the following:
(add-to-list 'load-path "/path/to/helm/directory") ; facultative when installed with make install
(require 'helm)
(require 'helm-autoloads)
or with use-package
:
(add-to-list 'load-path "/path/to/helm/directory") ; facultative when installed with make install
(use-package helm :config (require 'helm-autoloads))
For further configuration like changing bindings in the helm-map
you
will likely want to use a delayed method like with-eval-after-load
or use-package
to avoid loading all of Helm at startup.
As example you can have a look at the maintainer helm config here.
To setup specific variables from the helm session you are in, use C-h c
.
You may want as well to enable helm completion everywhere in Emacs,
for this use (helm-mode 1)
.
Now you may want to try some helm commands from the emacs menu
(toolbar) or starting with e.g. C-x c C-x C-f
.
Once you find some useful commands for you, bind them to a more
convenient key than with the C-x c
prefix.
For more complex configuration have a look at the maintainer config.
People often think helm is just something like ido 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.
However Helm is divided in two distinct categories of commands, the helm
natives commands that provide a feature not existing in Emacs or a new
implementation of an existing Emacs feature and the helmized commands
that are 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…).
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.
Differences between the two often trip up new users.
Emacs completion is based on the minibuffer. Helm completion is based on the completion window.
In default 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.
- Type until the desired candidate is highlighted, or navigate to it using
C-n
.
- Type until the desired candidate is highlighted, or navigate to it using
- Hitting
RET
selects the currently highlighted item in the completion window.
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.
Helm’s functionality needs only a few general key bindings as shown below. These are also documented in the mode line.
-
<tab>
orC-i
lists available actions -
C-j
orC-z
invokes the persistent action -
M-SPC
orC-SPC
orC-@
marks a candidate -
C-h m
displays the embeded help in an org buffer without quitting helm session. -
RET
runs the first action of action list
Yank symbol at point from helm-current-buffer
(i.e. buffer where a helm command was invoked):
M-n
copies symbol at point to minibuffer
C-w
appends word next to point to the minibuffer and advance to next
word, hitting C-_
undo last insertion and rewind yank point in helm-current-buffer
-
helm-command-prefix-key
is the prefix for the preconfigured helm menu. -
C-x c
is the default key binding forhelm-command-prefix-key
. -
helm-M-x
and then type “helm” to discover Helm commands.- This is the same as running
helm-command-prefix-key
followed byM-x
.
- This is the same as running
- The
Helm > All commands
menu item is another way to discover helm commands.- It runs
helm-execute-helm-command
.
- It runs
-
helm-command-prefix-key
followed by any regular Emacs key invokes the Helm version of the same command.- E.g.
helm-M-x
forM-x
.
- E.g.
To run the helm version of a command with a key binding, set it in your init file as follows:
(global-set-key (kbd "M-x") 'helm-M-x)
-
C-h m
shows Helm commands and currently active key bindings.
- Invoke
M-x
, then type “helm” to browse other Helm tools.
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
.
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.
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:
- In your init file, turn on
helm-mode
. - In the
helm-mode
customize group, add a key tohelm-completing-read-handlers-alist
forfind-file-read-only
with valueido
, 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)
MELPA and other repositories have many useful extensions, some of which are redundant as Helm already provides them. Review if they already exist as part of the default Helm package before downloading new extensions.
(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.
The new Helm workflow uses fewer buffers. Whereas the old workflow opened many Dired buffers stacked in the workspace, the new approach uses virtual Dired buffers without cluttering the buffer list with many Dired buffers. The decluttering of buffers also helps with running helm-locate
without conflicts; there’s also less need to resort to other workarounds, such as running helm-multi-files
.
The new approach uses helm-find-files
as the starting point, never opens Dired buffers yet provides easy access to common Helm commands, such as grep
, locate
, find
, etc. These Helm commands, moreover, are not limited to the current directory because Helm now allows marking files in other directories before running the commands.
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 ofhelm-find-files
-
C-c h
to access the full history of files (file-name-history
) -
C-x C-f
switches back tohelm-find-files
Use emacs-helm.sh as a advanced cd
command similar to broot
:
hcd () {
helm --chdir $(pwd) -nw --eval "(progn (helm-set-local-variable 'helm-full-frame t) \
(setq helm-ff-auto-update-initial-value t) \
(let ((file (read-file-name \"File: \"))) \
(if (file-directory-p file) (kill-emacs (format \"cd '%s'\" file)) (find-file file))))"
}
Add this function to .bashrc.
NOTE: helm
is available when installing from source (with make
install).
- Helm on GitHub
- Tuhdo’s Helm tutorial
- Helm mailing list (Google Group)
-
Helm Gmane (
gmane.emacs.helm.user
)
- Prefer using Org mode for Wiki pages.
- Install the toc-org package to automatically generate tables of contents.
- Edit the Wiki.
- Before saving, run
toc-org-insert-toc
.- Consider adding something like the following to
before-save-hook
to do this automatically:
- Consider adding something like the following to
(defun *-org-insert-toc ()
"Create table of contents (TOC) if current buffer is in
`org-mode'."
(when (= major-mode 'org-mode)
toc-org-insert-toc))