Table of Contents
- Hop configuration
- Ensuring your configuration is sound
- Setting up your keys
- Configure the quit_key
- Jumping on sole occurrence with jump_on_sole_occurrence
- Case insensitivity with case_insensitive
- Control highlight autocommands with create_hl_autocmd
- Change the display of the labels with uppercase_labels
- Current line only mode with current_line_only
- Jump across windows with multi_windows
- Change the jump position with hint_position
- Offset the jump with hint_offset
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Hop configuration
Configuring Hop is a pretty straight-forward process. The only thing you need to do is to call the setup function
from the Lua API:
require'hop'.setup {
-- Hop configuration goes there
}
The possible configuration options are explained in a user-friendly way in this page. If you want to get an exhaustive list with default values of the all the configuration options without a guided tour, feel free to use:
:h hop-config
Note
: some configuration options, like
current_line_onlyormulti_windowsdo not really make sense when configured globally insetup. It is recommended to set them by overriding Lua calls instead. Indeed, everything that you put insetupcan be passed to Lua invocations command, overriding what’s insetup. See the rest of the wiki for further information.
Ensuring your configuration is sound
At any time, if you are experiencing issues with Hop, you can check its health with the following command:
:checkhealth hop
Setting up your keys
The keys configuration option is one of the most important, if not the most. It’s a string that must contain unique
characters. Characters showing up first (i.e. left-most) will be used first when creating labels for the hints to jump
to. That option is important because Hop highly depends on your keyboard layout. The goal is to type characters that
are close to your home row and limiting wrist movements. The default option is set for QWERTY. If you are using
something else, it is highly recommended that you customize keys to yield the best experience possible.
For instance, for people using the bépo keyboard layout, keys can be set to:
require'hop'.setup {
keys = 'etovxqpdygfblzhckisuran',
}
Configure the quit_key
That option allows you to change the key that you must type while Hop is active to abort / quit it. It defaults to
<ESC>, which is a sane default for most people.
require'hop'.setup {
quit_key = '<SPC>',
}
Jumping on sole occurrence with jump_on_sole_occurrence
Sometimes, you will trigger a Hop command that will only hint a single item. In such a case, the default behavior is
to automatically jump to it. You can control that behavier with jump_on_sole_occurrence:
require'hop'.setup {
jump_on_sole_occurrence = false,
}
Case insensitivity with case_insensitive
When using commands such as HopChar* or HopPattern, the default is be case insensitive: searching for a will hint
both a and A.
Case insensitivity respects
smartcase. So if you have setsmartcasetotrue,abcwill be fully case insensitive, whileAbcwill be case sensitive.
You can go case sensitive with the following:
require'hop'.setup {
case_insensitive = false,
}
Control highlight autocommands with create_hl_autocmd
By default, Hop will inject its own highlighting. This is a default option that is sound for most people but can be annoying at some time (you want to write the highlights yourself, or you are using a theme plugin that resets them).
You can prevent Hop from automatically inserting the autocommands for highlighting with:
require'hop'.setup {
create_hl_autocmd = false,
}
Change the display of the labels with uppercase_labels
Labels are displayed by printing the content of your keys. You can switch to upper case if you want with:
require'hop'.setup {
uppercase_labels = true,
}
Current line only mode with current_line_only
This configuration option is probably not to be set in setup but by using the Lua API. By default, Hop actions
will take place for the whole visible part of the buffer, unless modified by variations. current_line_only is a kind
of variation that will scope Hop to the same line as the the one the cursor is on.
You can switch all Hop actions to current line only with the following:
require'hop'.setup {
current_line_only = true,
}
Jump across windows with multi_windows
By default, Hop works in the buffer attached to the currently selected windows. You can make Hop hint every buffer in every visible windows in your terminal with the following setting:
require'hop'.setup {
multi_windows = true,
}
Change the jump position with hint_position
When Hop hints items in a buffer, it actually hints two things: the beginning and the end of the target. That is
especially true for HopPattern and HopWord. Of course, some Hop commands will have both their beginning and end
overlapping, like HopChar1, HopLine and HopLineStart, for instance.
By default, Hop will jump to the beginning part of the jump target. You can switch to the end with:
require'hop'.setup {
hint_position = require'hop.hint'.HintPosition.END,
}
Even more exotic: jump to the middle!
require'hop'.setup {
hint_position = require'hop.hint'.HintPosition.MIDDLE,
}
Offset the jump with hint_offset
A very powerful feature: by default, Hop will jump to the target position. However, you can offset that position
with hint_offset. That is especially useful to reimplement motions such as t / T, which move the cursor right
before the actual thing you asked for. In that case, you would use hint_offset = -1.
If you want to always jump after the jump target, you can for instance use this:
require'hop'.setup {
hint_offset = 1,
}
It is highly discouraged to set hint_offset in setup though. Have a look at the rest of the wiki to reimplement t / T or other kind of interesting motions.
