merge: rewrite-docs
I've omitted docs/*.org from this merge, as there is still work left to do there, but I am pushing the module docs early so folks can benefit from the new docs sooner.
This commit is contained in:
Henrik Lissner
commit
1f8bf7accb
179 changed files with 13125 additions and 8630 deletions
|
|
@ -1,28 +1,10 @@
|
|||
#+TITLE: completion/ivy
|
||||
#+DATE: February 13, 2017
|
||||
#+SINCE: v2.0
|
||||
#+STARTUP: inlineimages
|
||||
# -*- mode: doom-docs-org -*-
|
||||
#+title: :completion ivy
|
||||
#+subtitle: Yesterday's lightest search engine
|
||||
#+created: February 20, 2017
|
||||
#+since: 2.0.0
|
||||
|
||||
* Table of Contents :TOC_3:noexport:
|
||||
- [[#description][Description]]
|
||||
- [[#module-flags][Module Flags]]
|
||||
- [[#plugins][Plugins]]
|
||||
- [[#hacks][Hacks]]
|
||||
- [[#prerequisites][Prerequisites]]
|
||||
- [[#features][Features]]
|
||||
- [[#jump-to-navigation][Jump-to navigation]]
|
||||
- [[#project-search--replace][Project search & replace]]
|
||||
- [[#in-buffer-searching][In-buffer searching]]
|
||||
- [[#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-fuzzynon-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
|
||||
* Description :unfold:
|
||||
This module provides Ivy integration for a variety of Emacs commands, as well as
|
||||
a unified interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep/][ripgrep]].
|
||||
|
||||
|
|
@ -31,63 +13,87 @@ I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's
|
|||
lighter, simpler and faster in many cases.
|
||||
#+end_quote
|
||||
|
||||
** Module Flags
|
||||
+ =+fuzzy= Enables fuzzy completion for Ivy searches.
|
||||
+ =+prescient= Enables prescient filtering and sorting for Ivy searches.
|
||||
+ =+childframe= Causes Ivy to display in a floating child frame, above Emacs.
|
||||
+ =+icons= Enables file icons for switch-{buffer,project}/find-file counsel
|
||||
commands.
|
||||
** Maintainers
|
||||
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
|
||||
|
||||
** 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/raxod502/prescient.el][prescient]]* (=+prescient=)
|
||||
+ [[https://github.com/tumashu/ivy-posframe][ivy-posframe]]* (=+childframe=)
|
||||
+ [[https://github.com/asok/all-the-icons-ivy][all-the-icons-ivy]]* (=+icons=)
|
||||
** Module flags
|
||||
- +childframe ::
|
||||
Display Ivy windows in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an popup buffer. *Requires
|
||||
GUI Emacs.*
|
||||
- +fuzzy ::
|
||||
Enable fuzzy completion for Ivy searches.
|
||||
- +icons ::
|
||||
Enable file icons for switch-{buffer,project}/find-file commands.
|
||||
- +prescient ::
|
||||
Enable prescient filtering and sorting for Ivy searches.
|
||||
|
||||
** Packages
|
||||
- [[doom-package:][all-the-icons-ivy]]* if [[doom-module:][+icons]]
|
||||
- [[doom-package:][amx]]
|
||||
- [[doom-package:][counsel]]
|
||||
- [[doom-package:][counsel-projectile]]
|
||||
- [[doom-package:][flx]]* if [[doom-module:][+fuzzy]]
|
||||
- [[doom-package:][ivy]]
|
||||
- [[doom-package:][ivy-hydra]]
|
||||
- [[doom-package:][ivy-posframe]]* if [[doom-module:][+childframe]]
|
||||
- [[doom-package:][ivy-rich]]
|
||||
- [[doom-package:][prescient]]* if [[doom-module:][+prescient]]
|
||||
- [[doom-package:][swiper]]
|
||||
- [[doom-package:][wgrep]]
|
||||
|
||||
** Hacks
|
||||
+ Functions with ivy/counsel equivalents have been globally remapped (like
|
||||
- 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
|
||||
- ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex
|
||||
command)
|
||||
|
||||
* Prerequisites
|
||||
This module has no prerequisites.
|
||||
** TODO Changelog
|
||||
# This section will be machine generated. Don't edit it by hand.
|
||||
/This module does not have a changelog yet./
|
||||
|
||||
* 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:
|
||||
* Installation
|
||||
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
|
||||
|
||||
This module has only one requirement: [[https://github.com/BurntSushi/ripgrep][Ripgrep]], which is a hard dependency of
|
||||
Doom itself, so you should already have it installed.
|
||||
|
||||
Otherwise, Counsel (an Ivy plugin) provides many commands to interface with a
|
||||
variety of programs from [[https://github.com/junegunn/fzf][fzf]] to [[https://kapeli.com/dash][Dash docsets]] to [[https://www.passwordstore.org/][pass]] and /much/ more. These
|
||||
programs are optional for this module, but must be installed if you intend to
|
||||
use their associated Helm command or plugin.
|
||||
|
||||
* TODO Usage
|
||||
#+begin_quote
|
||||
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||||
#+end_quote
|
||||
|
||||
[[doom-package:][ivy]] is a /large/ framework for completing things. Covering all its features is
|
||||
not within the scope of this module's documentation, so only its highlights will
|
||||
be covered here.
|
||||
|
||||
** Jump-to 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.
|
||||
Command-T, this module provides similar functionality by bringing [[doom-package:][projectile]] and
|
||||
[[doom-package:][ivy]] together.
|
||||
|
||||
https://assets.doomemacs.org/completion/ivy/projectile.png
|
||||
|
||||
| Keybind | Description |
|
||||
|----------------------+-------------------------------------|
|
||||
| =SPC p f=, =SPC SPC= | Jump to file in project |
|
||||
| =SPC f f=, =SPC .= | Jump to file from current directory |
|
||||
| =SPC s i= | Jump to symbol in file |
|
||||
| Keybind | Description |
|
||||
|------------------+-------------------------------------|
|
||||
| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project |
|
||||
| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory |
|
||||
| [[kbd:][SPC s i]] | Jump to symbol in file |
|
||||
|
||||
** Project search & replace
|
||||
This module provides interactive text search and replace using ripgrep.
|
||||
|
||||
| Keybind | Description |
|
||||
|-----------+--------------------------|
|
||||
| =SPC s p= | Search project |
|
||||
| =SPC s P= | Search another project |
|
||||
| =SPC s d= | Search this directory |
|
||||
| =SPC s D= | Search another directory |
|
||||
| Keybind | Description |
|
||||
|---------+--------------------------|
|
||||
| [[kbd:][SPC s p]] | Search project |
|
||||
| [[kbd:][SPC s P]] | Search another project |
|
||||
| [[kbd:][SPC s d]] | Search this directory |
|
||||
| [[kbd:][SPC s D]] | Search another directory |
|
||||
|
||||
https://assets.doomemacs.org/completion/ivy/search.png
|
||||
|
||||
|
|
@ -96,7 +102,6 @@ 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 |
|
||||
|------------------------+------------------------------------------------------------------|
|
||||
| ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) |
|
||||
|
|
@ -108,65 +113,79 @@ commands.
|
|||
-----
|
||||
|
||||
These keybindings are available while a search is active:
|
||||
| Keybind | Description |
|
||||
|---------+-----------------------------------------------|
|
||||
| [[kbd:][C-c C-o]] | Open a buffer with your search results |
|
||||
| [[kbd:][C-c C-e]] | Open a writable buffer of your search results |
|
||||
| [[kbd:][C-SPC]] | Preview the current candidate |
|
||||
| [[kbd:][C-RET]] | Open the selected candidate in other-window |
|
||||
|
||||
| Keybind | Description |
|
||||
|-----------+-----------------------------------------------|
|
||||
| =C-c C-o= | Open a buffer with your search results |
|
||||
| =C-c C-e= | Open a writable buffer of your search results |
|
||||
| =C-SPC= | Preview the current candidate |
|
||||
| =C-RET= | Open the selected candidate in other-window |
|
||||
|
||||
Changes to the resulting wgrep buffer (opened by =C-c C-e=) can be committed
|
||||
with =C-c C-c= and aborted with =C-c C-k= (alternatively =ZZ= and =ZQ=, for evil
|
||||
users).
|
||||
Changes to the resulting wgrep buffer (opened by [[kbd:][C-c C-e]]) can be committed with
|
||||
[[kbd:][C-c C-c]] and aborted with [[kbd:][C-c C-k]] (alternatively [[kbd:][ZZ]] and [[kbd:][ZQ]], for evil users).
|
||||
|
||||
https://assets.doomemacs.org/completion/ivy/search-replace.png
|
||||
|
||||
** In-buffer searching
|
||||
The =swiper= package provides an interactive buffer search powered by ivy. It
|
||||
The [[doom-package:][swiper]] package provides an interactive buffer search powered by ivy. It
|
||||
can be invoked with:
|
||||
|
||||
+ =SPC s s= (~swiper-isearch~)
|
||||
+ =SPC s S= (~swiper-isearch-thing-at-point~)
|
||||
+ =SPC s b= (~swiper~)
|
||||
+ ~:sw[iper] [QUERY]~
|
||||
- [[kbd:][SPC s s]] (~swiper-isearch~)
|
||||
- [[kbd:][SPC s S]] (~swiper-isearch-thing-at-point~)
|
||||
- [[kbd:][SPC s b]] (~swiper~)
|
||||
- ~:sw[iper] [QUERY]~
|
||||
|
||||
https://assets.doomemacs.org/completion/ivy/swiper.png
|
||||
|
||||
A wgrep buffer can be opened from swiper with =C-c C-e=.
|
||||
A wgrep buffer can be opened from swiper with [[kbd:][C-c C-e]].
|
||||
|
||||
** Ivy integration for various completing commands
|
||||
*** General
|
||||
| Keybind | Description |
|
||||
|----------------+---------------------------|
|
||||
| =M-x=, =SPC := | Smarter, smex-powered M-x |
|
||||
| =SPC '= | Resume last ivy session |
|
||||
| Keybind | Description |
|
||||
|------------+---------------------------|
|
||||
| [[kbd:][M-x]], [[kbd:][SPC :]] | Smarter, smex-powered M-x |
|
||||
| [[kbd:][SPC ']] | Resume last ivy session |
|
||||
|
||||
*** Jump to files, buffers or projects
|
||||
| Keybind | Description |
|
||||
|----------------------+---------------------------------------|
|
||||
| =SPC RET= | Find bookmark |
|
||||
| =SPC f f=, =SPC .= | Browse from current directory |
|
||||
| =SPC p f=, =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 |
|
||||
| Keybind | Description |
|
||||
|------------------+---------------------------------------|
|
||||
| [[kbd:][SPC RET]] | Find bookmark |
|
||||
| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory |
|
||||
| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project |
|
||||
| [[kbd:][SPC f r]] | Find recently opened file |
|
||||
| [[kbd:][SPC p p]] | Open another project |
|
||||
| [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace |
|
||||
| [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer |
|
||||
|
||||
*** Search
|
||||
| Keybind | Description |
|
||||
|-----------+-------------------------------------------|
|
||||
| =SPC p t= | List all TODO/FIXMEs in project |
|
||||
| =SPC s b= | Search the current buffer |
|
||||
| =SPC s d= | Search this directory |
|
||||
| =SPC s D= | Search another directory |
|
||||
| =SPC s i= | Search for symbol in current buffer |
|
||||
| =SPC s p= | Search project |
|
||||
| =SPC s P= | Search another project |
|
||||
| =SPC s s= | Search the current buffer (incrementally) |
|
||||
| Keybind | Description |
|
||||
|---------+-------------------------------------------|
|
||||
| [[kbd:][SPC p t]] | List all TODO/FIXMEs in project |
|
||||
| [[kbd:][SPC s b]] | Search the current buffer |
|
||||
| [[kbd:][SPC s d]] | Search this directory |
|
||||
| [[kbd:][SPC s D]] | Search another directory |
|
||||
| [[kbd:][SPC s i]] | Search for symbol in current buffer |
|
||||
| [[kbd:][SPC s p]] | Search project |
|
||||
| [[kbd:][SPC s P]] | Search another project |
|
||||
| [[kbd:][SPC s s]] | Search the current buffer (incrementally) |
|
||||
|
||||
* TODO Configuration
|
||||
#+begin_quote
|
||||
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||||
#+end_quote
|
||||
|
||||
* Configuration
|
||||
** TODO Enable fuzzy/non-fuzzy search for specific commands
|
||||
** TODO Change the position of the ivy childframe
|
||||
|
||||
* TODO Troubleshooting
|
||||
/There are no known problems with this module./ [[doom-report:][Report one?]]
|
||||
|
||||
* Frequently asked questions
|
||||
[[doom-suggest-faq:][Ask a question?]]
|
||||
|
||||
** Helm vs Ivy vs Ido vs Vertico
|
||||
See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]].
|
||||
|
||||
* TODO Appendix
|
||||
#+begin_quote
|
||||
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
|
||||
#+end_quote
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue