108 lines
6.4 KiB
Org Mode
108 lines
6.4 KiB
Org Mode
#+TITLE: :completion ivy
|
|
|
|
This module adds Ivy, a completion backend.
|
|
|
|
#+begin_quote
|
|
I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's lighter.
|
|
#+end_quote
|
|
|
|
+ Project-wide search & replace powered by ~rg~ or ~ag~
|
|
+ Project jump-to navigation ala Command-T, Sublime Text's Jump-to-anywhere or Vim's CtrlP plugin.
|
|
+ Ivy integration for ~M-x~, ~imenu~, ~recentf~ and others.
|
|
+ A powerful, interactive in-buffer search using ~swiper~.
|
|
+ Ivy-powered TODO/FIXME navigation
|
|
|
|
* Table of Contents :TOC:
|
|
- [[#install][Install]]
|
|
- [[#macos][MacOS]]
|
|
- [[#arch-linux][Arch Linux]]
|
|
- [[#usage][Usage]]
|
|
- [[#project-search--replace][Project search & replace]]
|
|
- [[#jump-to-file-project-navigation][Jump-to-file project navigation]]
|
|
- [[#in-buffer-searching][In-buffer searching]]
|
|
- [[#task-lookup][Task lookup]]
|
|
- [[#appendix][Appendix]]
|
|
- [[#commands][Commands]]
|
|
- [[#hacks][Hacks]]
|
|
|
|
* Install
|
|
This module optionally depends on [[https://github.com/BurntSushi/ripgrep][ripgrep]] and [[https://github.com/ggreer/the_silver_searcher][the_silver_searcher]].
|
|
|
|
~rg~ is faster, but its results aren't deterministic, neither does it support multiline search or full PCRE, that's where ~ag~ is useful.
|
|
|
|
** MacOS
|
|
#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
|
|
brew install ripgrep the_silver_searcher
|
|
#+END_SRC
|
|
|
|
** Arch Linux
|
|
#+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
|
|
sudo pacman --needed --noconfirm -S ripgrep the_silver_searcher
|
|
#+END_SRC
|
|
|
|
* Usage
|
|
Here is some insight into how I use this module. Keep in mind that the referenced commands and keybindings are defined [[/modules/private/hlissner][in my private module]].
|
|
|
|
** Project search & replace
|
|
Ex interfaces to Ag (the silver searcher) and Rg (ripgrep) are available: ~:ag[!]~ and ~:rg[!]~, or their current-directory counterparts ~:agcwd[!]~ and ~:rgcwd[!]~.
|
|
|
|
[[/../screenshots/modules/completion/ivy/ivy-search.gif]]
|
|
|
|
From this session, you can press =S+Tab= to create a writeable occur-buffer in wgrep mode.
|
|
|
|
[[/../screenshots/modules/completion/ivy/ivy-search-replace.gif]]
|
|
|
|
Make your modifications and press =C-c C-c= to commit them, or =C-c C-k= to abort.
|
|
|
|
** Jump-to-file project navigation
|
|
Inspired by Sublime Text's jump-to-anywhere, Vim's CtrlP or Unite plugins, and Textmate's Command-T, a marriage of ~projectile~ and ~ivy~ makes this available to you in Emacs. Invoke it with =SPC f /=, =SPC SPC= or ~counsel-projectile-find-file~.
|
|
|
|
[[/../screenshots/modules/completion/ivy/ivy-projectile.gif]]
|
|
|
|
** In-buffer searching
|
|
I use ~evil-search~ (invoked by pressing =/= in normal mode) when jumping small/moderate (or predictable) distances. However, there are occasions where I need more feedback, so I turn to ~swiper~ (available directly with =M-x swiper RET=, or via ~:sw[iper]~).
|
|
|
|
[[/../screenshots/modules/completion/ivy/ivy-swiper.gif]]
|
|
|
|
** Task lookup
|
|
I sprinkle my projects with TODO's & FIXME's. You can navigate to and peruse them via ~M-x +ivy/tasks~ or ~:todo[!]~ (ex command).
|
|
|
|
[[/../screenshots/modules/completion/ivy/ivy-todo.gif]]
|
|
|
|
* Appendix
|
|
** Commands
|
|
Here is a list of my commonly used commands, their default keybinds (defined in [[../../private/hlissner/+bindings.el][private/hlissner/+bindings.el]]), and their corresponding ex command (defined in [[../../private/hlissner/+commands.el][private/hlissner/+commands.el]]).
|
|
|
|
| command | key / ex command | description |
|
|
|-------------------------------------+------------------------+------------------------------------------------------------------|
|
|
| ~counsel-M-x~ | =M-x= | Smarter, smex-powered M-x |
|
|
| ~counsel-bookmark~ | =SPC RET= | Find bookmark |
|
|
| ~counsel-find-file~ | =SPC f .= or =SPC .= | Browse from current directory |
|
|
| ~counsel-projectile-find-file~ | =SPC f /= or =SPC SPC= | Find file in project |
|
|
| ~counsel-projectile-switch-project~ | =SPC p p= | Open another project |
|
|
| ~counsel-recentf~ | =SPC f r= | Find recently opened file |
|
|
| ~ivy-switch-buffer~ | =SPC b b= | Jump to buffer in current workspace |
|
|
| ~+ivy/switch-workspace-buffer~ | =SPC b B= | Jump to buffer across workspaces |
|
|
| ~+ivy:ag~ | ~:ag[!] [QUERY]~ | Search project (BANG = ignore gitignore) |
|
|
| ~+ivy:ag-cwd~ | ~:agcwd[!] [QUERY]~ | Search this directory (BANG = don't recurse into subdirectories) |
|
|
| ~+ivy:rg~ | ~:rg[!] [QUERY]~ | Search project (if BANG, ignore gitignore) |
|
|
| ~+ivy:rg-cwd~ | ~:rgcwd[!] [QUERY]~ | Search this directory (BANG = don't recurse into subdirectories) |
|
|
| ~+ivy:swiper~ | ~:sw[iper] [QUERY]~ | Search current buffer |
|
|
| ~+ivy:todo~ | ~:todo[!]~ | List all TODO/FIXMEs in project (or current file if BANG) |
|
|
|
|
While in a search (e.g. invoked from ~+ivy:ag~ or ~+ivy:rg~), these new keybindings are available to you:
|
|
|
|
| key | description |
|
|
|-------------+--------------------------------------------------------------------------------|
|
|
| =<backtab>= | Perform search/replace on the search results (open occur buffer in wgrep mode) |
|
|
| =C-SPC= | Preview the current candidate |
|
|
| =M-RET= | Open the selected candidate in other-window |
|
|
|
|
** Hacks
|
|
+ Functions with ivy/counsel equivalents have been globally remapped (like ~find-file~ => ~counsel-find-file~). So a keybinding to ~find-file~ will invoke ~counsel-find-file~ instead.
|
|
+ ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex command)
|
|
+ ~counsel-[arp]g~'s parentheses quoting behavior was reversed. Now, if you
|
|
want literal parentheses, you must escape them: e.g. ~\(match\)~ is literal,
|
|
~(match)~ is a regexp group.
|
|
|
|
|