How to use Ivy, Swiper & Counsel in Emacs for Noobs

Sometimes I wonder if I’m dumb, or the documentation just isn’t meant for noobs. Learning to use Emacs efficiently can be frustrating if you need a little extra hand holding. In this post I’m going to hold your hand and walk you through using Swiper, Ivy, and Counsel. We’ll talk about what each package does so you can know what does what.

Note: Please leave a comment correcting any mistakes, or to add anything I missed!
This page is a work in progress.

Ivy Github page

Swiper, Ivy, Counsel Manual

Ivy

Ivy is just an “Interactive completion interface” meaning it helps you type less and get the stuff you need faster. When you run an ivy command you can type to narrow down the results.

Ivy is available through Melpa. To install, run:

M-x package-install RET ivy RET in the Emacs mini-buffer.

To enable: M-x ivy-mode

Ivy Usage:

Refresh Emacs, enable ivy-mode, and run:

M-x (alt-x).

If Ivy is working properly, you’ll notice the mini-buffer is larger, and lists some options for you to choose from. If you start typing, Ivy will narrow down your options to stuff that matches what you type.

Thanks to regular expressions, you can even type a space, and type more to narrow your search based on multiple words.

You can use C-n and C-p to scroll up and down through the mini buffer matches as well, so type to narrow down the results, and C-n or C-p to select the exact option.

Ivy integrates with other commands out of the box too. C-x d (dired), C-x C-f (Find file), and probably other commands are enhanced with Ivy.

That is Ivy in a nutshell. By itself, Ivy is useful, but it can integrate with many packages in Emacs to make Ivy much more powerful, and that’s where Counsel, Swiper, etc… come in.

Swiper

Swiper helps you search through emacs, and shows you text around the matching terms. It turns out Ivy is actually required for Swiper to work. If you install Swiper, Ivy gets installed as a dependency.

Install Swiper (via Melpa): M-x package-install RET swiper RET in the Emacs mini-buffer.

Add the following to your .emacs file to prepare swiper and Ivy:

(ivy-mode 1)
(global-set-key "\C-s" 'swiper)

Now, you can search through Emacs using Swiper. When you run C-s the swiper search will be used instead of isearch. When you search you can use the same regular expression Ivy has to find a specific result you’re looking for.

Just like with Ivy, you can use “C-n” and “C-p” to scroll up and down through the matching terms.

Counsel

Counsel appears to provide additional functions for various ivy and swiper commands. Counsel is available via Melpa, and will automatically install both Swiper AND Ivy as dependencies.

Install Counsel (via Melpa): M-x package-install RET counsel RET

Now we’ll take a look at one counsel command to see how counsel works. counsel-find-file.

Run M-x counsel-find-file

Now, find the file you want to select, and just make it highlighted. Once the file is highlighted, run M-o and a list of “actions” will show up. You can now do several different things with this file, like open it regularly, or open it in a new window.

Without Counsel, running M-o would not give you as many options. That is the benefit of counsel.

Useful Customizations

That’s how they all work individually… sort of… Ivy is the only package that can be installed by itself. Swiper relies on Ivy, and Counsel relies on both Swiper and Counsel.

Now we can take a look at some cool stuff that these packages provide.

Note: Don’t just copy my config blindly. Some of these settings are specific to a Linux Distro with a Window Manager. See highlighted lines.

;;Ivy, Counsel, Swiper Setup
;;
;;
;;
(ivy-mode 1) ;; Turn on ivy by default
(setq ivy-use-virtual-buffers t)  ;; no idea, but recommended by project maintainer
(setq enable-recursive-minibuffers t) ;; no idea, but recommended by project maintainer
(setq ivy-count-format "(%d/%d) ")  ;; changes the format of the number of results
(global-set-key (kbd "C-s") 'swiper)  ;; replaces i-search with swiper
(global-set-key (kbd "M-x") 'counsel-M-x) ;; Gives M-x command counsel features
(global-set-key (kbd "C-x C-f") 'counsel-find-file) ;; gives C-x C-f counsel features
(global-set-key (kbd "<f1> f") 'counsel-describe-function)
(global-set-key (kbd "<f1> v") 'counsel-describe-variable)
(global-set-key (kbd "<f1> l") 'counsel-find-library)
(global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol) 
(global-set-key (kbd "<f2> u") 'counsel-unicode-char)  
(global-set-key (kbd "C-c C-r") 'ivy-resume) 

(global-set-key (kbd "C-c g") 'counsel-git)
(global-set-key (kbd "C-c j") 'counsel-git-grep)
(global-set-key (kbd "C-c k") 'counsel-ag) ;; add counsel/ivy features to ag package
(global-set-key (kbd "C-x l") 'counsel-locate)
(global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
;;(define-key read-expression-map (kbd "C-r") 'counsel-expression-history)

;;set action options during execution of counsel-find-file
;; replace "frame" with window to open in new window
(ivy-set-actions
 'counsel-find-file
 '(("j" find-file-other-frame "other frame")
   ("b" counsel-find-file-cd-bookmark-action "cd bookmark")
   ("x" counsel-find-file-extern "open externally")
   ("d" delete-file "delete")
   ("r" counsel-find-file-as-root "open as root")))

;; set actions when running C-x b
;; replace "frame" with window to open in new window
(ivy-set-actions
 'ivy-switch-buffer
 '(("j" switch-to-buffer-other-frame "other frame")
   ("k" kill-buffer "kill")
   ("r" ivy--rename-buffer-action "rename")))

;;
;;
;; End Ivy, Swiper, Counsel

Conclusion:

Ivy relies on nothing. Swiper relies on Ivy, and Counsel relies on both Swiper and Ivy. Ivy helps you narrow down results when searching for something by typing. Swiper is a replacement for isearch. Counsel gives you extra functions that aren’t normally available.

The whole bundle is a very general package that helps you search for stuff, and they integrate with a lot of other packages, so learning to use Ivy, Swiper, and Counsel can really help you improve your speed in Emacs. Did I miss anything? Let me know in the comments!

You must have an account and be logged in to solve challenges and lessons!