avy

Jump to things in Emacs tree-style

Subscribe to updates I use avy


Statistics on avy

Number of watchers on Github 645
Number of open issues 24
Average time to close an issue 4 days
Main language Emacs Lisp
Average time to merge a PR about 6 hours
Open pull requests 4+
Closed pull requests 26+
Last commit 4 months ago
Repo Created almost 3 years ago
Repo Last Updated about 1 month ago
Size 405 KB
Organization / Authorabo-abo
Latest Release0.4.0
Contributors18
Page Updated
Do you use avy? Leave a review!
View open issues (24)
View avy activity
View on github
Latest Open Source Launches
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating avy for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Introduction

avy is a GNU Emacs package for jumping to visible text using a char-based decision tree. See also ace-jump-mode and vim-easymotion - avy uses the same idea.

logo

Command overview

You can bind some of these useful commands in your config.

avy-goto-char

Input one char, jump to it with a tree.

(global-set-key (kbd "C-:") 'avy-goto-char)

After C-: b:

avy-goto-char

avy-goto-char-2

Input two consecutive chars, jump to the first one with a tree.

The advantage over the previous one is less candidates for the tree search. And it's not too inconvenient to enter two consecutive chars instead of one.

(global-set-key (kbd "C-'") 'avy-goto-char-2)

After C-' bu:

avy-goto-char-2

avy-goto-char-timer

Input an arbitrary amount of consecutive chars, jump to the first one with a tree.

This is a more flexible version of avy-goto-char-2. First part works similarly to isearch: you type a query and it's highlighted dynamically on the screen. When you stop typing for avy-timeout-seconds (0.5s by default), you'll be able to select one of the candidates with avy.

avy-goto-line

Input zero chars, jump to a line start with a tree.

(global-set-key (kbd "M-g f") 'avy-goto-line)

After M-g f:

avy-goto-line

You can actually replace the M-g g binding of goto-line, since if you enter a digit for avy-goto-line, it will switch to goto-line with that digit already entered.

avy-goto-word-1

Input one char at word start, jump to a word start with a tree.

(global-set-key (kbd "M-g w") 'avy-goto-word-1)

After M-g wb:

avy-goto-word-1

avy-goto-word-0

Input zero chars, jump to a word start with a tree.

Compared to avy-goto-word-1, there are a lot more candidates. But at a least there's not need to input the initial char.

(global-set-key (kbd "M-g e") 'avy-goto-word-0)

After M-g e:

avy-goto-word-0

Org-mode commands

  • avy-org-goto-heading-timer: Type part of an Org heading. When you stop typing, if only one heading on the screen matches, it will be jumped to; if more than one matches, you can jump to a heading with Avy. This is like avy-goto-char-timer but for Org headings.
  • avy-org-refile-as-child: With point in an entry you want to refile, run this command, select a heading with Avy, and the entry will be refiled as its first child heading. This makes it quick and easy to refile to headings that are visible on-screen, even to other windows or buffers.

Other commands

There are some more commands which you can explore yourself by looking at the code.

Bindings

You add this to your config to bind some stuff:

(avy-setup-default)
(global-set-key (kbd "C-c C-j") 'avy-resume)

It will bind, for example, avy-isearch to C-' in isearch-mode-map, so that you can select one of the currently visible isearch candidates using avy.

Customization

See the comprehensive custom variable list on the defcustom wiki page.

See how to write your own avy commands on the custom-commands wiki page.

Contributing

Copyright Assignment

Avy is subject to the same copyright assignment policy as Emacs itself, org-mode, CEDET and other packages in GNU ELPA. Any legally significant contributions can only be accepted after the author has completed their paperwork. Please see the request form if you want to proceed.

The copyright assignment isn't a big deal, it just says that the copyright for your submitted changes to Emacs belongs to the FSF. This assignment works for all projects related to Emacs. To obtain it, you need to send one email, then send one letter (if you live in the US, it's digital), and wait for some time (in my case, I had to wait for one month).

Style

The basic code style guide is to use (setq indent-tabs-mode nil). It is provided for you in .dir-locals.el, please obey it.

Before submitting the change, run make compile and make test to make sure that it doesn't introduce new compile warnings or test failures. Also run make checkdoc to see that your changes obey the documentation guidelines.

Use your own judgment for the commit messages, I recommend a verbose style using magit-commit-add-log.

avy open issues Ask a question     (View All Issues)
  • over 1 year key binding(s) to change target action?
  • over 1 year goto char in word an move to end of the word
  • almost 2 years functions to resume last jump, and jump to prev/next match from last jump
  • almost 2 years Inconsistent use of order of characters in avy-keys
  • almost 2 years Suggestion: Add lines/regions to kill ring
  • over 2 years Small incompatibility with prettify-symbols-mode
avy open pull requests (View All Pulls)
  • Add new command `avy-move-region'
  • Add basic support for repeating searches
  • Add kill and save region/lines functionality.
  • Add kill and save region/lines functionality.
avy list of languages used
avy latest release notes
0.4.0 avy 0.4.0

Table of Contents

  • Fixes
    • avy-goto-char-timer obeys avy-styles-alist
    • Add de-bruijn to the defcustom of avy-styles-alist
    • Respect the current input method for target chars
    • avy-goto-subword-0 shouldn't offer invisible chars
    • Better case-fold-search handling
    • Add misc punctuation to subword commands
    • Add padding for wide-width chars (ex. Japanese and Chinese)
    • avy-goto-line
    • Push mark for numeric line
    • Allow numeric prefix arg
    • Work for visual-line-mode
    • Don't error on end of buffer
    • Obey avy-background
    • Fix for narrowed regions
    • Don't modify avy-action
    • avy-goto-char-timer
    • May read as many chars as you want
    • Highlight matches while reading chars
    • Highlight depending on avy-all-windows
    • Make faster for org-mode
    • Add case fold search
    • avy-copy-region
    • Keep the same selectors for the second pass
    • Copy/move to initial window
    • Search only in the visible region
    • Fix jumping to the last char of a folded Org outline
    • Fix for both org-indent-mode and visual-line-mode
    • Beep when there are no matches
    • Simplify overlay code
    • Fix de-bruijn no catch for tag
    • Fix overlays at point-max
    • Improve case-fold-search condition
    • Don't shorten selector string for visual-line-mode and bolp
    • Fix interaction with goto-address-mode
  • New Features
    • Allow non-printing keys in avy-keys
    • Allow to switch action midway from goto to kill/mark/copy
    • New command avy-pop-mark
    • New commands avy-goto-line-above and avy-goto-line-below
    • New defcustom avy-line-insert-style
    • New defcustom avy-all-windows-alt
    • New defcustom avy-subword-extra-word-chars

0.4.0

Fixes

avy-goto-char-timer obeys avy-styles-alist

See #67.

Add de-bruijn to the defcustom of avy-styles-alist

See #73.

Respect the current input method for target chars

See #76.

avy-goto-subword-0 shouldn't offer invisible chars

See #90.

Better case-fold-search handling

See #87.

Add misc punctuation to subword commands

See #93.

Add padding for wide-width chars (ex. Japanese and Chinese)

See #96.

avy-goto-line

Push mark for numeric line

See #74.

Allow numeric prefix arg

The old behavior remains for ARG 1 or 4. For all other ARG, simply go to that line. See #86.

Work for visual-line-mode

See #91.

Don't error on end of buffer

See #91.

Obey avy-background

See #94.

Fix for narrowed regions

See #122, #123.

Don't modify avy-action

See #124.

avy-goto-char-timer

May read as many chars as you want

See #97.

Highlight matches while reading chars

See #98.

Highlight depending on avy-all-windows

See #104.

Make faster for org-mode

See #100.

Add case fold search

See #128.

avy-copy-region

Keep the same selectors for the second pass

See #120, #121.

Copy/move to initial window

See #131.

Search only in the visible region

See #108, #109.

Fix jumping to the last char of a folded Org outline

See #108.

Fix for both org-indent-mode and visual-line-mode

See #110.

Beep when there are no matches

See #111.

Simplify overlay code

Most functions reuse avy--overlay now.

Fix de-bruijn no catch for tag

See #116.

Fix overlays at point-max

See #125.

Improve case-fold-search condition

See #126.

Don't shorten selector string for visual-line-mode and bolp

See #129.

Fix interaction with goto-address-mode

New Features

Allow non-printing keys in avy-keys

Now you can set avy-keys also to the arrow keys and page up/down, e.g.

(setq avy-keys '(left right up down prior next))

and those will be displayed as , , , , , in the overlays. The display is controlled by the variable avy-key-to-char-alist.

See #77.

Allow to switch action midway from goto to kill/mark/copy

For example, suppose you have:

(global-set-key (kbd "M-t") 'avy-goto-word-1)
  • To jump to a certain word starting with w (e.g. first one on screen): M-t w a
  • To copy the word instead of jumping to it: M-t w na.
  • To mark the word after jumping to it: M-t w ma.
  • To kill the word after jumping to it: M-t w xa.

You can customize avy-dispatch-alist to modify these actions.

See #78.

New command avy-pop-mark

Goes back to the last location of push-mark:

  • has its own history,
  • handles multiple frames.

See #81 #88 #69.

New commands avy-goto-line-above and avy-goto-line-below

See #106.

New defcustom avy-line-insert-style

Allows to modify the behavior of avy-copy-line, avy-move-line, and avy-copy-region. See #117.

New defcustom avy-all-windows-alt

Allows to customize the behavior of universal-argument modifying avy-all-windows. See #118.

New defcustom avy-subword-extra-word-chars

Allows to customize the behavior of avy-goto-subword-0 and avy-goto-subword-1 by adding extra chars that should match as word constituents. See #116.

0.3.0 avy 0.3.0

avy 0.3.0

Fixes

Candidate window reversal

See #27.

Jumping to newlines with at-full style

See #5.

Stop at-full style from shifting text sometimes

See #5.

Fix at-full interaction with tabs

When at a tab, visualize it using tab-width spaces.

See #43.

Fix overlay issue when the same buffer is in two windows

See #47 and http://debbugs.gnu.org/cgi/bugreport.cgi?bug=20607.

Quote punctuation chars

See #63.

Update screenshot for avy-goto-char in README.md

Use C-: as the new suggested binding instead of the pi char.

See #64.

New Features

avy-goto-line can now break into goto-line

Just enter a digit and you'll be transferred into goto-line prompt with that digit already entered. This means that you can just bind M-g g to avy-goto-line without losing anything.

See #29.

avy-goto-line now works with all kinds of overlay styles

Any of the following do something different now:

(setq avy-styles-alist
      '((avy-goto-line . post)))
(setq avy-styles-alist
      '((avy-goto-line . at)))
(setq avy-styles-alist
      '((avy-goto-line . at-full)))
(setq avy-styles-alist
      '((avy-goto-line . pre)))

See #17.

New defcustom avy-case-fold-search

Non-nil when searches should ignore case, so e.g. avy-goto-char b will match both b and B. On by default. Use this to turn off this behavior:

(setq avy-case-fold-search nil)

See #34.

New command avy-goto-word-or-subword-1

Enter one char, and select a visible word or subword that starts with it, depending on subword-mode. Move the point there.

See #33.

avy-move-line should remove empty line after original one is moved

See #40.

avy-move-line now takes a prefix arg

Use e.g. M-3 before avy-move-line to move 3 lines at once.

Most commands can be used non-interactively

Example:

(defun avy-goto-lp ()
  (interactive)
  (avy-goto-char ?\())

This command only goes to the ( character. This is actually very similar to lispy-ace-paren, except the implementation is only one line.

See #44.

(almost) all defcustoms are explained on the wiki

See the defcustom wiki page.

Allow all operations to work across frames

You have to customize avy-all-windows for this. By default, it's set to work on all windows on the current frame.

To make it work only on the current window, use:

(setq avy-all-windows nil)

To make it work on all frames, use:

(setq avy-all-windows 'all-frames)

New command avy-goto-char-in-line

This is avy-goto-char reduced only to the current line. Few candidates means very short decision chars path.

See #49.

New overlay style de-bruijn

How to use it:

(setq avy-style 'de-bruijn)

What it does: when your leading chars are clumped up together, it's impossible to overlay the decision path without shifting the buffer text a bit. For example, with the word buffer, you avy-goto-char b, and:

  • the path for the first f is aj
  • the path for the second f is ak

It's not possible to overlay 4 characters over ff in buffer. But to with de-bruijn style, which results in the path being aj and jk. It's possible to overlay ajk just fine.

Pros and cons of de-bruijn over other styles:

  • a pro is that it's possible to display the full decision path for clumped up chars, which is truncated for other styles
  • a con is that the decision path is of the same length (e.g. 2 or 3) for all candidates, while with other styles it's possible to have a few candidets with a shorter path.

See #51 and #5.

New defcustom avy-ignored-modes

This is meant for visual modes like doc-view-mode or image-mode that can have a huge number of chars in a single window. Which results in a huge number of candidates even in other windows.

Current setting:

(setq avy-ignored-modes '(image-mode doc-view-mode pdf-view-mode))

See #57.

New tutorial on writing custom commands

See the the custom-commands wiki page and #55.

New face setup

New variable avy-lead-faces will determine the faces used to color the current decision depth you're in. For example, if to select a particular candidate you need to press abc:

  • a will be highlighted with a face that corresponds to depth 3
  • b will be highlighted with a face that corresponds to depth 2
  • c will be highlighted with a face that corresponds to depth 1

But if another candidate needs ef:

  • e will be highlighted with a face that corresponds to depth 2
  • f will be highlighted with a face that corresponds to depth 1

See #53.

New variable avy-translate-char-function

You can use this, for example, to interpret one character as another in avy-keys.

Example:

(setq avy-translate-char-function
          (lambda (c) (if (= c 32) ?a c)))

This will translate SPC (32) into a. So you can press either a or SPC to mean a.

avy-isearch works for different styles

See #61.

Switch the default style from pre to at-full

I've come to like at-full more than pre over time. The difference is that pre hides no chars in your buffer, while at-full doesn't shift text.

Use this to restore the previous default behavior:

(setq avy-style 'pre)
0.2.0 avy 0.2.0

Fixes

  • avoid processing image-mode and doc-view-mode buffers
  • the jump characters are regexp-quote-ed
  • pressing RET during char selection will select end of line positions
  • avy-background works better if you're selecting among multiple windows

New Features

avy-goto-subword-0 and avy-goto-subword-1

These commands rely on subword for more precise location of subwords.

avy-setup-default

This is a function call that you can put in your config:

(avy-setup-default)

For now it only binds C-' to avy-isearch in isearch-mode-map. It's autoloaded, so you can even omit (require 'avy) in your config.

avy-goto-char-timer

This is an amalgamation of avy-goto-char (which uses one narrowing char) and avy-goto-char-2 (which uses two narrowing chars). If you input two chars quickly (<0.5s by default), the latter is called. Otherwise, the former is called.

Customize the keys per-command

You can customize avy-keys as the all-purpose keys:

(setq avy-keys '(?a ?s ?d ?f ?g ?h ?j ?k ?l))

In addition, you can customize these keys per-command:

(setq avy-keys-alist
      `((avy-goto-word-0 .
                         ,(append (number-sequence ?A ?Z)
                                  (number-sequence ?a ?z)))
        (avy-goto-word-1 . (?f ?g ?j ?k))))

In this case, avy-goto-word-0 gets 72 decision keys, while avy-goto-word-1 gets only 4, and all others get avy-keys.

Customize the style per-command

You can customize avy-style as the all-purpose style (the default is 'pre):

(setq avy-style 'at-full)

In addition, you can customize the style per-command:

(setq avy-styles-alist
      `((avy-goto-char-2 . post)))

I think that 'post the a style best suited specifically for avy-goto-char-2 since you already type two chars in a sequence, so a third one right after is appropriate. Same for avy-isearch, that one is always 'post.

Obsoletes

Anything that's prefixed with avi- is now obsolete. I'll keep the obsolete declarations for around a month, but you should switch before warnings turn into errors. avy-goto-char-style and avy-goto-word-style are obsolete as well.

Other projects in Emacs Lisp