Welcome to the Emacs-helm wiki! ------ This wiki hosts helm documentation but is not User editable. Changes are welcomed by submitting a Pull Request for [Home.mdpp][1]. ------ !TOC # Wiki maintainer instructions 1. Checkout wiki repo at `git@github.com:emacs-helm/helm.wiki.git` 2. Get markdown-pp at https://github.com/thierryvolpiatto/markdown-pp.git 3. Install markdown-pp For help on setup.py: `$ sudo python setup.py help` For installing: `$ sudo python setup.py install` 4. Edit on helm repo `Home.mdpp`. 5. Run markdown.pp.py: (This will create the table of contents) `$ path/to/markdown-pp.py Home.mdpp Home.md` See the [Readme][2] for more details. 6. Merge the resulting file `Home.md` with the one on the helm wiki repo you checked out in 1. # Install First get the files from git repo: Helm git repo is at: You will find there tarballs of differents versions. To get it with git: git clone https://github.com/emacs-helm/helm Once you have the helm directory, `cd` to it and run `make`. Edit your `~/.emacs.el` file and add: (add-to-list 'load-path "/path/to/helm/directory") (require 'helm-config) # General helm commands Helm allow you to have few binding to remember unlike all others Emacs applications. Thus, all bindings are auto documented. Helm show you by default in mode-line the most useful bindings, you will see in headers of helm buffer some more specific commands. So when helm start what you have to remember: - Access to action menu with TAB - Use persistent actions with C-z - Mark candidate with M- So three bindings to remember and they are anyway documented in mode-line. For more, hitting C-h m while in helm session will show you all other bindings. NOTE: Some helm commands have a special keymap, you can access infos on these keymap with `C-c ?`, it should be documented in mode-line. ## Yanking text To yank the symbol at point from `helm-current-buffer` (i.e. buffer where a helm command originated): M-n Alternatively, customize `helm-yank-symbol-first` to enable C-w to always yank the whole symbol on first invocation. # Overview of preconfigured helm commands For starting with helm, a set of commands have been set for you in 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 from menu helm all commands (helm-execute-helm-command). Or run helm-M-x (`helm-command-prefix-key` `M-x`) and type helm. When you like a command, e.g `helm-command-prefix-key` `M-x` you should bind it to something more convenient like M-x to replace the Emacs original keybinding. # Helm Find Files `helm-find-files` provide you a way to navigate in your system file easily. All the actions you can do on files from here are described in this section. It is binded in menu, and in `helm-command-map` to `helm-command-prefix-key` `C-x C-f`. We will assume you have binded `helm-find-files` to `C-x C-f`. To do that put in your `.emacs.el`: (global-set-key (kbd "C-x C-f") 'helm-find-files) It is well integrated with tramp, you can enter any tramp filename and it will complete. (e.g /su::, /sudo::, /ssh:host:, ... etc) Called with a prefix arg, (C-u) helm-find-files will show you also history of last visited directories. ## Navigation Helm-find-files is not by default on / but on default-directory or thing-at-point as it use ffap.If you are on a url, a mail adress etc.. it will do the right thing. So helm-find-files work like find-file (C-x C-f), but if you use it with helm-match-plugin.el, you have to add a space and then the next part of pattern you want to match: Example: Find Files or url: ~/ That show all ~/ directory. Find Files or url: ~/des will show all what begin with "des" Find Files or url: ~/ esk (Notice the space after ~/) will show all what contain esk. Find Files or url: ~/ el$ Will show all what finish with el You can move in the helm buffer with C-n C-p or arrow keys, when you are on a file, you can hit C-z to show only this file-name in the helm buffer. On a directory, C-z will switch to this directory to continue searching in it. On a symlink C-z will expand to the true name of symlink.(moving your mouse cursor over a symlink will show the true name of it). So it is quite easy to navigate in your files with helm-find-files. Forget to mention C-. that go to root of current dir or to precedent level of dir. So for example you can hit C-z and then come back immediatly where you were with C-. instead of erasing minibuffer input with DEL. On non graphic display, it is bound to C-l. If `helm-ff-lynx-style-map` is non–nil, you will be able to use `left` instead of C-l and `right` instead of C-z. If you like it, you can safely bind it to C-x C-f to replace the standard find-file: (global-set-key (kbd "C-x C-f") 'helm-find-files) NOTE: Starting helm-find-files with C-u will show you a little history of the last visited directories. ## Jump with nth commands Take advantage of the second, third and 4th actions in helm. Instead of opening action menu with TAB, just hit: `C-e` for 2th action `C-j` for 3th action You can bind 4th action to some key like this: (define-key helm-map (kbd "") 'helm-select-4th-action) ## Helm find files action shortcuts Instead of having to open action pannel with TAB, you have some convenients shortcuts to quickly run actions. Use C-c ? from an helm-find-files session to have a description. ## Turn in image viewer You can turn helm-find-files in a nice image-viewer. Navigate to your image directory, then type C-u C-z on first image. Now turn on `follow-mode` with C-c C-f. You can now navigate in your image directory with arrow up and down or C-n C-p. Don`t forget also to use C-t to split you windows vertically if needed. You will find also two actions to rotate image in action menu. To use these actions whitout quitting, use M-l (rotate left) and M-r (rotate right). Of course M-l and M-r have no effect if candidate is not an image file. Don`t forget to use `C-t` to split windows vertically, and then `C-}' and `C-{' to narrow/enlarge helm window. NOTE: It use image-dired in background, so if image-dired doesn't work for some reason, this will not work too. Be sure to have Imagemagick package installed. ## Serial rename You can rename files with a new prefix name and by incremental number. The marked files will be renamed with a new prefix name and starting at the start-number you have choosen. Note that the marked files are in the order of the selection you did, this allow to reorder files. If you mark files in other directories than the current one, these files will be moved or symlinked to current one. TIP: If you have more than 100 files to serial rename, start at 100 instead of one to have your directory sorted correctly. You have three ways to serial rename: - By renaming: All the file of others directories are moved in directory where renaming happen. - By symlinking: All the files that are not files of the directory where you want to rename will be symlinked, others will be renamed. - By copying: All the file of others directories are copied in directory where renaming happen. Example of Use: I want to create a directory with many symlinked images coming from various directories. 1) C-x C-f (launch helm-find-files) 2) Navigate to the place of your choice and write new directory name ending with `/` and press RET. 3) Navigate and browse images, when you want an image mark it, you can mark all in a directory with M-a. 4) When you have marked all files, choose `serial rename by symlinking` in action menu. 5) Choose new name and start number. 6) Navigate to initial directory (where files will be renamed/symlinked) and RET. 7) Say yes to confirm, that`s done. 8) Start viewing your pictures. ## Open Files Externally You will find in action menu from helm-find-files an action to open file with external program. If you have no entry in .mailcap or /etc/mailcap, you will enter an helm session to choose a program to use with this kind of file. It will offer to you to save setting to always open this kind of files with this program. Once configured, you can however open the files of same extension with some other program by forcing helm to choose program with C-u. NOTE: You can now open files externally with `C-c C-x` from helm-find-files. ## Eshell command on files You can run eshell-command on files or marked files, the command you use have to accept one file as argument. The completion is make on your eshell aliases. This allow you creating personal actions for `helm-find-files`. ## Why Eshell - Because eshell allow you to create aliases. - Because eshell accept shell commands but also elisp functions. All these command should end with https://github.com/emacs-helm/helm/blob/master/doc/Home.mdpp. You will have completion against all these aliases once eshell is loaded. (start it once before using helm-find-files). ## Setup Aliases Go in eshell, an enter at prompt: alias my_alias command $1 NOTE: don`t forget to escape the $. See the documentation of Eshell for more info. ## Problem starting Eshell Eshell code is available (autoloaded) only when you have started once eshell. That`s annoying like many autoloaded stuff in Emacs. Here how to start Eshell at emacs startup: Add this to your .emacs: (add-hook 'emacs-startup-hook #'(lambda () (let ((default-directory (getenv "HOME"))) (command-execute 'eshell) (bury-buffer)))) ## Dired Commands To enable some of the usual commands of dired, put in .emacs.el (helm-dired-bindings 1) Or run interactively: M-x helm-dired-bindings This will replace in dired C, R, S, and H commands. That is copy, rename, symlink, hardlink. When creating a symlink, you will find relsymlink in actions menu.(TAB). NOTE: This is deprecated for Emacs24 users, use instead `helm-mode`. ## Copy Files It is a powerful feature of helm-find-files as you can mark files in very different places in your file system and copy them in one place. Dired is not able to do that, you can mark files only in current dired display and copy them somewhere. So, easy to use, just mark some files, and hit copy files in the action menu. That will open a new helm-find-files where you can choose destination. ## Rename Files Just mark some files, and hit rename files in the action menu. That will open a new helm-find-files where you can choose destination. ## Symlink Files Just mark some files, and hit symlink or relsymlink files in the action menu. That will open a new helm-find-files where you can choose destination. ## Hardlink Just mark some files, and hit hardlink files in the action menu. That will open a new helm-find-files where you can choose destination. ## Follow file after action A prefix arg on any of the action above, copy, rename, symlink, hardlink, will allow you to follow the file. For example, when you want to copy an elisp file somewhere and you want to compile it in this place, hitting C-u RET will bring you in this place with the file already marked, you have just to go in action menu to compile it. ## In Buffer File Completion In any buffer and even in minibuffer if you have enable recursive-minibuffer (setq enable-recursive-minibuffers t) You can have completion with C-x C-f and then hit tab to choose action `Complete at point` once you have found the filename you want. `Create File` Navigate to the directory where you want to create your new file, then continue typing the name of your file and type enter. NOTE: If your filename ends with a / you will be prompt to create a new directory. ## Create Directory Navigate to the directory where you want to create your new directory, then continue typing the name of new directory - Parents accepted - and end it with / type enter, you will be prompt to create your new directory (possibly with parents). ## Ediff files Well, that is easy to use, move cursor to a file, hit ediff in action menu, you will jump in another helm-find-files to choose second file. ## Ediff merge files move cursor to a file, hit ediff merge in action menu, you will jump in another helm-find-files to choose second file. ## Browse archive with avfs If you have installed avfs (See: http://sourceforge.net/projects/avf) you can browse archives in your directory .avfs once it is mounted with `mountavfs`. Just move on the archive filename and press C-z (persistent action) and you will see in helm buffer the subdirectories of archive, just navigate inside as usual. ## Helm write buffer That is a replacement of standard `write-buffer` Emacs command with helm completion. ## Helm insert file That is a replacement of standard `insert-file` Emacs command with helm completion. # Grep We describe here helm-do-grep, an incremental grep. It is really convenient as you can start a search just after finding the place or file(s) you want to search in. By the nature of incremental stuff, it is faster than original Emacs grep for searching. As you type the display change (like in all other helm commands). This grep is also recursive unlike the emacs implementation that use find/xargs. It support wildcard and (re)use the variables `grep-find-ignored-files` and `grep-find-ignored-directories`. It have full tramp integration. (you can grep file on a remote host or in su/sudo methods). - NOTE: When using it recursively, `grep-find-ignored-files` is not used unless you don`t specify the only extensions of files where you want to search (you will have a prompt). You can now specify more than one extension to search. e.g \*.el \*.py \*.tex will search only in files with these extensions. - NOTE: Windows users need grep version `2.5.4` of Gnuwin32 on windoze. This version should accept the `--exclude-dir` option. - NOTE: Apple OS X users also need a version of grep that accepts `--exclude-dir` This is installable from homebrew with: brew install https://raw.github.com/Homebrew/homebrew-dupes/master/grep.rb ## Helm do grep Start with M-x helm-do-grep bound to `helm-command-prefix-key` `M-g s` (A prefix arg will launch recursive grep). ## Grep from helm-find-files From helm-find-files (`helm-command-prefix-key` `C-x C-f`) Open the action menu with tab and choose grep. A prefix arg will launch recursive grep. - NOTE:You can now launch grep with (C-u) M-g s without switching to the action pannel. ## Grep One file Just launch grep, it will search in file at point. if file is a directory, it will search in ALL files of this directory like: grep -nH -e pattern * ## Grep Marked files Just mark some files with C- and launch grep. ## Grep marked files from differents directories This is a very nice feature of helm grep implementation that allow to search in specific files located not only in current directory but anywhere in your file system. To use navigate in your file system and mark files with C- When you have marked all files, just launch grep in action menu. NOTE: Using prefix-arg (C-u) will start a recursive search with the extensions of the marked files except if those are one of `grep-find-ignored-files`. ## Grep Directory recursively From `helm-find-files`, reach the root of the directory where you want to search in, then hit TAB to open the action menu and choose grep with a prefix arg (i.e C-u RET). If you want to launch helm-do-grep recursively without starting `helm-find-files`, do: C-u helm-command-prefix-key M-g s NOTE: If you forget to hit `C-u` before `M-g s` you can do it after file selection. You will be prompted for selecting in which category of files to search: Use the wilcard syntax like \*.el for example (search in only `.el` files). By default, the extension of the file at point is used when cursor is on a filename. If cursor is at root of directory, all the filename extensions found in directory and not matching `grep-find-ignored-files` are inserted in prompt. ## Grep Using Wildcard You can use wildcard: From the root of your directory, if you want for example to search files with .el extension: add \*.el to prompt. ## Grep thing at point Before lauching helm, put your cursor on the start of symbol or sexp you will want to grep. Then launch helm-do-grep or helm-find-files, and when in the grep prompt hit C-w as many time as needed. ## Grep persistent action As always, C-z will bring you in the buffer corresponding to the file you are grepping. Well nothing new, but using C-u C-z will record this place in the mark-ring. So if you want to come back later to these places no need to grep again, you will find all these places in the mark-ring. Accessing the mark-ring in Emacs is really inconvenient, fortunately, you will find in helm-config `helm-all-mark-ring` which is a mark-ring browser (helm-command-prefix-key C-c SPACE). `helm-all-mark-ring` is in helm menu also, in the tool section. - TIP: Bind `helm-all-mark-ring` to C-c SPACE. (global-set-key (kbd "C-c ") 'helm-all-mark-rings) - NOTE: `helm-all-mark-ring` handle global-mark-ring also. ## Save grep session If you want to save the results of your grep session, doing `C-x C-s` will save your grep results in a `helm-grep-mode` buffer. NOTE: You can save differents named helm grep buffers. If you haven't saved your grep session in a named buffer, you can anyway retrieve the last session with `helm-resume`. # Helm M-x It is binded to `helm-command-prefix-key` `M-x`, you should bind it to `M-x`. Features: - You can use prefix arguments before or during M-x session - C-z is a toggle documentation for this command - The key binding of command are shown. # Helm regexp This is a replacement of regexp-builder. The groups are shown in a convenient way. # Query replace regexp Write your regexp in helm-regexp, when it match what you want, you can run query-replace from action menu. NOTE: Before running helm-regexp, you can select a region to work in, that will narrow this region automatically. {Save regexp as sexp} When you use this, it will save your regexp for further use in lisp code, with backslash duplicated. ## Save regexp as string Save the regexp as you wrote it. ## Helm locate First be sure you have a locate program installed on your system. Most GNU/Linux distro come with locate included, you update or create the data base with `updatedb` command. ## Search files To use, just launch M-x helm-locate Then enter filename at prompt. It will search this pattern entered also in directory and subdirectory names, to limit your search to basename, add `-b` after pattern. The search is performed on all files known in database, they maybe not exists anymore, so to limit to really existing files add after pattern `-e`. To limit you search to specific number of results, use `-n` after your pattern with the number of results you want. Example: Pattern: emacs -b -e -n 12 You can also launch `helm-locate` from `helm-find-files`, just do `C-x C-f`. (With a prefix arg it will let you choose a local DB file) ## Launch grep When search is done, you can search in a specific file or directory with grep that you will find in action menu (TAB). - NOTE:You can now launch grep with (C-u) M-g s without switching to the action pannel. ## Use a local locate DB You can specify a specific database with prefix argument ARG (C-u). Many databases can be used: navigate and mark them. See also `helm-locate-with-db`. To create a user specific db, use: updatedb -l 0 -o dbpath -U directory Where `dbpath` is a filename matched by `helm-locate-db-file-regexp` # Windows specificity On Windows you should use Everything program that mimic locate, is very fast and don't need to update database manually. To use with helm-locate, you will need his command line named `es`. Be sure to modify the PATH environment variable, to include path to the directory that contain `es`. # Helm Etags ## Create the tag file To use etags in Emacs you have first to create a TAGS file for your project with the etags shell command. If your directory contains subdirectories use someting like:(e.g .el files) find . -iregex .*\.el$ | xargs etags Otherwise etags *.el is enough For more infos see the man page of etags. ## Start helm etags Now just using `helm-command-prefix-key` `e` will show you all entries. If the project is big it take some time to load tag file but when it is done, next search will be very fast. If you modify the TAGS file, use C-u C-u helm-command-prefix-key e to refresh the tag cache. To search the definition at point use just C-u helm-command-prefix-key e # Firefox bookmarks You will have to set firefox to import bookmarks in his html file book-marks.html. (only for firefox versions >=3) To achieve that, open `about:config` in firefox and double click on this line to enable value to true : user_pref("browser.bookmarks.autoExportHTML", false); You should have now : user_pref("browser.bookmarks.autoExportHTML", true); Now you can use M-x helm-firefox-bookmarks To see your firefox bookmarks from Emacs. When you are in firefox things are a little more complicated. You will need wmctrl program and a script named ffbookmarks : #!/bin/bash wmctrl -xa emacs emacsclient -e "(progn (helm-firefox-bookmarks) nil)" > /dev/null wmctrl -xa firefox exit 0 Put this script somewhere in PATH and make it executable : chmod +x ffbookmarks Firefox is not aware about this new protocol, you will have to instruct it. See Firefox documentation or use firefox-protocol.el package you can get here: Install new protocol: M-x firefox-protocol-installer-install to install new protocol ffbookmarks Then install a bookmarklet in firefox : Right click on the bookmark toolbar in firefox and add a new bookmark called ffbookmarks. Add this instead of url: javascript:location.href='ffbookmarks://localhost' Now when you click on ffbookmarks it will bring you in Emacs and allow you to browse your bookmarks with helm. NOTE : emacs server need to be started in the running Emacs, see Emacs documentation. # Helm for buffers M-x helm-buffers-list ## Borring buffers Will show you your buffers list without borring buffers defined by regexp in `helm-c-boring-buffer-regexp`. Just use customize to set that for your need. ## Search buffers by major-mode Once in this helm session, you can narrow your buffer list by `major-mode`, regexp as usual or the both: Example: I want to show all my buffer that are in emacs-lisp mode: Pattern: lisp will show all emacs-lisp and lisp related buffers. Now i want to limit these buffers to the one that match `any` Pattern: lisp any Now i want to limit these buffers to the one that match `any` but end with `foo`: Pattern: lisp any foo Note the space between any and foo. I want to match buffers that match `any` but not limited to lisp buffers: Pattern: any ## Different colors for buffers - If a buffer is modified, it will showup in orange. - If a buffer have been modified by some external program (e.g sed) in the back of emacs, it will showup in red. - Non–buffer file, Directory and files have differents face. # Special commands Not complete. `C-c ?` will show you all commands available. # Helm Resume You can resume an helm session at any moment. When called with a prefix arg allow choosing among different sessions. # Other tools In addition of what is described above, you will find a bunch of powerfull tools that come with helm-config.el. Just browse the helm commands availables with helm-M-x. Not complete. # Helm mode `helm-mode` will enable helm completion in all Emacs commands using `completing-read` or `read-file-name`. To use it: M-x helm-mode Turn it on in .emacs with: (helm-mode 1) Customize with: `helm-completing-read-handlers-alist` See C-h v `helm-completing-read-handlers-alist` for more infos. Not complete. # Helm Eshell completion ## Enable helm pcomplete Of course pcomplete is already enabled in Eshell, but what we want here is to enable it with helm support. To enable it's easy, just add to `.emacs.el`: > (add-hook 'eshell-mode-hook > #'(lambda () > (define-key eshell-mode-map > [remap pcomplete] > 'helm-esh-pcomplete))) Now when hitting `TAB`, you should have helm pcompletion. ## Write your own pcomplete functions You can enhance Emacs pcomplete by writing your own pcomplete functions. Here an example with `find` command: (defun pcomplete/find () (let ((prec (pcomplete-arg 'last -1))) (cond ((and (pcomplete-match "^-" 'last) (string= "find" prec)) (pcomplete-opt "HLPDO")) ((pcomplete-match "^-" 'last) (while (pcomplete-here '("-amin" "-anewer" "-atime" "-cmin" "-cnewer" "-context" "-ctime" "-daystart" "-delete" "-depth" "-empty" "-exec" "-execdir" "-executable" "-false" "-fls" "-follow" "-fprint" "-fprint0" "-fprintf" "-fstype" "-gid" "-group" "-help" "-ignore_readdir_race" "-ilname" "-iname" "-inum" "-ipath" "-iregex" "-iwholename" "-links" "-lname" "-ls" "-maxdepth" "-mindepth" "-mmin" "-mount" "-mtime" "-name" "-newer" "-nogroup" "-noignore_readdir_race" "-noleaf" "-nouser" "-nowarn" "-ok" "-okdir" "-path" "-perm" "-print" "-print0" "-printf" "-prune" "-quit" "-readable" "-regex" "-regextype" "-samefile" "-size" "-true" "-type" "-uid" "-used" "-user" "-version" "-warn" "-wholename" "-writable" "-xdev" "-xtype")))) ((string= "-type" prec) (while (pcomplete-here (list "b" "c" "d" "p" "f" "l" "s" "D")))) ((string= "-xtype" prec) (while (pcomplete-here (list "b" "c" "d" "p" "f" "l" "s")))) ((or (string= prec "-exec") (string= prec "-execdir")) (while (pcomplete-here* (funcall pcomplete-command-completion-function) (pcomplete-arg 'last) t)))) (while (pcomplete-here (pcomplete-entries) nil 'identity)))) ## Enable helm Eshell history Add this to `.emacs.el` > (add-hook 'eshell-mode-hook > #'(lambda () > (define-key eshell-mode-map > (kbd "M-p") > 'helm-eshell-history))) # Usefuls extensions Not complete. # Usefuls links You can have infos about helm on Github. You can ask on the helm mailing-list by subscribing at: Or at gmane: [gmane.emacs.helm.user](http://dir.gmane.org/gmane.emacs.helm.user) !REF [1]: https://github.com/emacs-helm/helm/blob/master/doc/Home.mdpp [2]: https://github.com/thierryvolpiatto/markdown-pp#readme