emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

completion/ivy: rewrite README (WIP)

Browse source
This commit is contained in:
Henrik Lissner 2019-01-03 02:12:50 -05:00
parent b1aca7dbed
commit fec0cb6b32
No known key found for this signature in database
GPG key ID: 5F6C0EA160557395
1 changed files with 204 additions and 118 deletions
Download patch file Download diff file Expand all files Collapse all files

322
modules/completion/ivy/README.org
View file

@ -1,128 +1,57 @@
#+TITLE: :completion ivy
#+TITLE: completion/ivy
#+DATE: February 13, 2017
#+SINCE: v2.0
#+STARTUP: inlineimages
This module adds Ivy, a completion backend.
* Table of Contents :TOC_3:noexport:
- [[Description][Description]]
- [[Module Flags][Module Flags]]
- [[Plugins][Plugins]]
- [[Hacks][Hacks]]
- [[Prerequisites][Prerequisites]]
- [[Install][Install]]
- [[MacOS][MacOS]]
- [[Arch Linux][Arch Linux]]
- [[Features][Features]]
- [[Jump-to-file project navigation][Jump-to-file project navigation]]
- [[Project search & replace][Project search & replace]]
- [[In-buffer searching][In-buffer searching]]
- [[Task lookup][Task lookup]]
- [[Ivy integration for various completing commands][Ivy integration for various completing commands]]
- [[General][General]]
- [[Jump to files, buffers or projects)][Jump to files, buffers or projects)]]
- [[Search][Search]]
- [[Configuration][Configuration]]
- [[Enable fuzzy/non-fuzzy search for specific commands][Enable fuzzy/non-fuzzy search for specific commands]]
- [[Change the position of the ivy childframe][Change the position of the ivy childframe]]
- [[Troubleshooting][Troubleshooting]]
* Description
This module provides Ivy integration for a variety of Emacs commands, as well as
a unified interface for project search and replace, powered by ag, rg, pt,
git-grep & grep (whichever is available).
#+begin_quote
I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's
lighter.
lighter, simpler and faster in many cases.
#+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
** Module Flags
+ =+fuzzy= Enables the fuzzy method for ivy searches.
+ =+childframe= Causes Ivy to display in a floating child frame, above Emacs.
*This requires GUI Emacs 26.1+*
* 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 (at the time of writing), 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.
** Project search & replace
There are four Ex interfaces for the silver searcher and ripgrep. They are:
+ ~:ag[!]~
+ ~:agcwd[!]~
+ ~:rg[!]~
+ ~:rgcwd[!]~
The optional BANG tells ag/rg to include ignored files in the search. And the
\*cwd variant of each command will only search in the current directory
(non-recursively).
[[/../screenshots/modules/completion/ivy/ivy-search.gif]]
Now, how do we do text replacements? With the ivy popup open you can press
=S+Tab= to create an wgrep buffer out of the results.
[[/../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/Unite plugins, and
Textmate's Command-T, a marriage of ~projectile~ and ~ivy~ makes this available
in Emacs.
Invoke it with =SPC f /=, =SPC SPC= or ~M-x 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/default/+bindings.el][private/default/+bindings.el]]), and their corresponding ex command (defined in
[[../../private/default/+evil-commands.el][private/default/+evil-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-workspace-buffer~ | =SPC b b= | Jump to buffer in current workspace |
| ~ivy-switch-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 |
** Plugins
+ [[https://github.com/abo-abo/swiper][ivy]]
+ [[https://github.com/abo-abo/swiper][counsel]]
+ [[https://github.com/ericdanan/counsel-projectile][counsel-projectile]]
+ [[https://github.com/abo-abo/swiper][swiper]]
+ [[https://github.com/abo-abo/swiper][ivy-hydra]]
+ [[https://github.com/yevgnen/ivy-rich][ivy-rich]]
+ [[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]]
+ [[https://github.com/DarwinAwardWinner/amx][amx]]
+ [[https://github.com/lewang/flx][flx]]* (=+fuzzy=)
+ [[https://github.com/tumashu/ivy-posframe][ivy-posframe]]* (=+childframe=)
** Hacks
+ Functions with ivy/counsel equivalents have been globally remapped (like
@ -131,4 +60,161 @@ keybindings are available to you:
+ ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex
command)
* Prerequisites
This module optionally depends on one of:
+ [[https://github.com/BurntSushi/ripgrep][ripgrep]] (rg)
+ [[https://github.com/ggreer/the_silver_searcher][the_silver_searcher]] (ag)
+ [[https://github.com/monochromegane/the_platinum_searcher][the_platinum_searcher]] (pt)
Ripgrep is recommended, but the order of its results aren't deterministic and it
doesn't support full PCRE (at the time of writing). The_silver_searcher is a
good alternative if either of these bother you.
If none of these are installed, file search commands will use git-grep (falling
back to grep, otherwise).
** Install
*** MacOS
#+BEGIN_SRC sh
brew install ripgrep the_silver_searcher
#+END_SRC
*** Arch Linux
#+BEGIN_SRC sh :dir /sudo::
sudo pacman --needed --noconfirm -S ripgrep the_silver_searcher
#+END_SRC
* Features
Ivy and its ilk are large plugins. Covering everything about them is outside of
this documentation's scope, so only Doom-specific Ivy features are listed here:
** Jump-to-file project navigation
Inspired by Sublime Text's jump-to-anywhere, CtrlP/Unite in Vim, and Textmate's
Command-T, this module provides similar functionality by bringing ~projectile~
and ~ivy~ together.
https://assets.doomemacs.org/completion/ivy/projectile.png
| Keybind | Description |
|----------------------+-------------------------------------|
| =SPC f /=, =SPC SPC= | Jump to file in project |
| =SPC f .=, =SPC .= | Jump to file from current directory |
** Project search & replace
This module provides interactive text search and replace using the first search
program available on your system (rg, ag, pt, git-grep or grep).
| Keybind | Description |
|----------------------+-------------------------------------|
| =SPC / b=, =M-f= | Search the current buffer |
| =SPC / p= | Search project |
| =SPC / d= | Search this directory |
| =SPC p t= | List all TODO/FIXMEs in project |
https://assets.doomemacs.org/completion/ivy/search.png
The ~+ivy-project-search-engines~ variable is consulted to determine which
underlying program to check for (and in what order). It's default value is ~'(rg
ag pt)~. If none of these are available, it will resort to =git-grep= (falling
back to =grep= after that).
To use a specific program, the following engine-specific commands are available
(but not bound to any key by default) for searching from the project root or the
current directory (recursively), respectively:
+ ~+ivy/ag~ / ~+ivy/ag-from-cwd~
+ ~+ivy/rg~ / ~+ivy/rg-from-cwd~
+ ~+ivy/pt~ / ~+ivy/pt-from-cwd~
+ ~+ivy/grep~ / ~+ivy/grep-from-cwd~
The universal argument (=SPC u= for evil users; =C-u= otherwise) changes the
behavior of these commands, instructing the underlying search engine to include
ignored files.
This module also provides Ex Commands for evil users:
| Ex command | Description |
|-----------------------+------------------------------------------------|
| ~:ag[!] [QUERY]~ | Search project w/ ag[fn:1] |
| ~:rg[!] [QUERY]~ | Search project w/ rg[fn:1] |
| ~:pt[!] [QUERY]~ | Search project w/ pt[fn:1] |
| ~:grep[!] [QUERY]~ | Search project w/ git-grep/grep[fn:1] |
| ~:agcwd[!] [QUERY]~ | Search this directory w/ the_silver_searcher |
| ~:rgcwd[!] [QUERY]~ | Search this directory w/ ripgrep |
| ~:ptcwd[!] [QUERY]~ | Search this directory w/ the_platinum_searcher |
| ~:grepcwd[!] [QUERY]~ | Search this directory w/ git-grep/grep |
The optional BANG functions is equivalent to the universal argument for the
previous commands.
-----
While in a search (e.g. invoked from ~+ivy:ag~ or ~:rg~), these extra
keybindings are available to you:
| Keybind | Description |
|---------+------------------------------------------------|
| =S-TAB= | Open a writable buffer of your search results |
| =C-SPC= | Preview the current candidate |
| =M-RET= | Open the selected candidate in other-window |
Changes to the resulting wgrep buffer (opened by =S-TAB=) can be committed with
=C-c C-c= and aborted with =C-c C-k=.
https://assets.doomemacs.org/completion/ivy/search-replace.png
** In-buffer searching
The =swiper= package provides an interactive buffer search powered by ivy. It
can be invoked with:
+ =SPC / b=
+ =M-f=
+ ~:sw[iper] [QUERY]~
https://assets.doomemacs.org/completion/ivy/swiper.png
A wgrep buffer can be opened from swiper with =S-TAB=.
** Task lookup
Some projects have TODO's and FIXME's littered across them. The ~+ivy/tasks~
command allows you to search and jump to them. It can be invoked with:
+ =SPC p t= (C-u = restrict search to current file)
+ ~:todo[!]~ (BANG = restrict search to current file)
https://assets.doomemacs.org/completion/ivy/todo.png
** Ivy integration for various completing commands
*** General
| Keybind | Description |
|----------------+---------------------------|
| =M-x=, =SPC := | Smarter, smex-powered M-x |
| =SPC '= | Resume last ivy session |
*** Jump to files, buffers or projects)
| Keybind | Description |
|---------------------------------+---------------------------------------|
| =SPC RET= | Find bookmark |
| =SPC f .=, =SPC .= | Browse from current directory |
| =SPC f /=, =SPC p /=, =SPC SPC= | Find file in project |
| =SPC f r= | Find recently opened file |
| =SPC p p= | Open another project |
| =SPC b b=, =SPC ,= | Switch to buffer in current workspace |
| =SPC b B=, =SPC <= | Switch to buffer |
*** Search
| Keybind | Description |
|------------------+------------------------------------------|
| =SPC / i= | Search for symbol in current buffer |
| =SPC / I= | Search for symbol in all similar buffers |
| =SPC / b=, =M-f= | Search the current buffer |
| =SPC / p= | Search project |
| =SPC / d= | Search this directory |
| =SPC p t= | List all TODO/FIXMEs in project |
* Configuration
** TODO Enable fuzzy/non-fuzzy search for specific commands
** TODO Change the position of the ivy childframe
* TODO Troubleshooting