awesome-emacs/doomemacs
1
0
Fork 0
mirror of https://github.com/doomemacs/doomemacs synced 2025-08-01 12:17:25 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
51d3b1b424e4d8dc086bbacafeb9dd6332c90fa6
doomemacs/modules/completion/ivy
History
Henrik Lissner 51d3b1b424 💥 revise advice naming convention (1/2) 
This is first of three big naming convention updates that have been a
long time coming. With 2.1 on the horizon, all the breaking updates will
batched together in preparation for the long haul.

In this commit, we do away with the asterix to communicate that a
function is an advice function, and we replace it with the '-a' suffix.
e.g.

  doom*shut-up -> doom-shut-up-a
  doom*recenter -> doom-recenter-a
  +evil*static-reindent -> +evil--static-reindent-a

The rationale behind this change is:

1. Elisp's own formatting/indenting tools would occasionally struggle
   with | and * (particularly pp and cl-prettyprint). They have no
   problem with / and :, fortunately.
2. External syntax highlighters (like pygmentize, discord markdown or
   github markdown) struggle with it, sometimes refusing to highlight
   code beyond these symbols.
3. * and | are less expressive than - and -- in communicating the
   intended visibility, versatility and stability of a function.
4. It complicated the regexps we must use to search for them.
5. They were arbitrary and over-complicated to begin with, decided
   on haphazardly way back when Doom was simply "my private config".

Anyhow, like how predicate functions have the -p suffix, we'll adopt the
-a suffix for advice functions, -h for hook functions and -fn for
variable functions.

Other noteable changes:
- Replaces advice-{add,remove}! macro with new def-advice!
  macro. The old pair weren't as useful. The new def-advice! saves on a
  lot of space.
- Removed "stage" assertions to make sure you were using the right
  macros in the right place. Turned out to not be necessary, we'll
  employ better checks later.
2019-07-22 02:27:45 +02:00
..
autoload
Fix (null uniquify-buffer-name-style) errors from ivy
2019-07-17 16:14:38 +02:00
config.el
💥 revise advice naming convention (1/2)
2019-07-22 02:27:45 +02:00
doctor.el
completion/ivy: fix header vars in doctor.el
2018-05-09 10:22:03 +02:00
packages.el
Add +prescient option for :completion ivy
2019-05-29 00:46:57 +10:00
README.org
completion/ivy: update keybinds in README #1491
2019-06-14 12:42:29 +02:00

README.org

completion/ivy

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).

I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's lighter, simpler and faster in many cases.

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. This requires GUI Emacs 26.1+
  • +icons Enables file icons for switch-{buffer,project}/find-file counsel commands.

Plugins

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)

Prerequisites

This module optionally depends on one of:

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 

brew install ripgrep the_silver_searcher

Arch Linux 

sudo pacman --needed --noconfirm -S ripgrep the_silver_searcher

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 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/ ag1
:rg[!] [QUERY] Search project w/ rg1
:pt[!] [QUERY] Search project w/ pt1
:grep[!] [QUERY] Search project w/ git-grep/grep1
: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
C-c C-e 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 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).

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
  • :sw[iper] [QUERY]

https://assets.doomemacs.org/completion/ivy/swiper.png

A wgrep buffer can be opened from swiper with C-c C-e.

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 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