Lately, I have received a PR on hop.nvim where the committer wanted to implement a feature… that was already there. I realized that even with a great documentation, a wiki, a changelog, official announcements, people still don’t read the documentation / feature list and implement things. The problem is that I have to reject their contributions and they lose time (and I do as well, because I have to review contributors’ code).

So here’s a quick article I can link in the super fresh TWiN, website I released a couple of days ago and that I hope will help with that kind of issues.

What can you do with Hop

Hop has been around for some time now. I created it back in February 2021, so roughly one year and a half. It has changed and evolved quite a lot ever since. New hint algorithm, new commands, a very big number of new options and features. I really recommand people to read the embedded documentation of Hop. Yes, completely. It took me time to write in a way that it will take you a couple of minutes only to read. So yes, do read it. Get the habit to read the embedded documentation of the plugins you install, especially after new updates. Or read TWiN from now on 😁.

The wiki, the wiki, the wiki!

Yes, Hop has a wiki. It’s available here and you should read a couple of pages from it:

The “default” commands.
Mastering advanced Hop. This part contains a couple of examples showing you how to use the various Hop Lua functions and options to create a really advanced motion platform.
All the configuration options.

Because I know some people will not click on those links and will still open PRs trying to implement features that are already there, here is a non-exhaustive list of advanced things you can already do, out of the box, with Hop.

Recreate `f`, `F`, `t` and `T`

It’s in the wiki and super simple. For that, you just need three options:

direction, which must be set with require'hop'.HintDirection.BEFORE_CURSOR or require'hop'.HintDirection.AFTER_CURSOR.
current_line_only, a boolean.
hint_offset, a super power allowing you to offset the actual jump off the jump target by a given number of characters.

So f is basically:

require'hop'.hint_char1({
  direction = require'hop.hint'.HintDirection.AFTER_CURSOR,
  current_line_only = true
})

F is then:

require'hop'.hint_char1({
  direction = require'hop.hint'.HintDirection.BEFORE_CURSOR,
  current_line_only = true
})

And in the same idea, t is:

require'hop'.hint_char1({
  direction = require'hop.hint'.HintDirection.AFTER_CURSOR,
  current_line_only = true,
  hint_offset = -1
})

And T:

require'hop'.hint_char1({
  direction = require'hop.hint'.HintDirection.BEFORE_CURSOR,
  current_line_only = true,
  hint_offset = -1
})

Jump at the end of things

Hop already can already understand the concept of beginning and end of a jump target. It does not make sense with all of them, but for most, it can. That is implemented with the hint_position option, which has to be one of:

require'hop.hint'.HintPosition.BEGIN
require'hop.hint'.HintPosition.MIDDLE
require'hop.hint'.HintPosition.END

So if you want to jump to the end of words:

require'hop'.words({
  hint_position = require'hop.hint'.HintPosition.END,
})

You can even jump right after the end of a word!

require'hop'.words({
  hint_position = require'hop.hint'.HintPosition.END,
  hint_offset = 1
})

Callbacks!

You can even use Hop to do something with the jump target that doesn’t imply jumping, like running a Lua function with the actual column and line where the hint is. It’s done with require'hop'.hint_with_callback.

Here, no example but an exercise for you: try to use require'hop'.hint_with_callback to send a notification (via vim.notify) displaying the jump target chosen by the user by hinting words. Tips: you will need to find the jump target generator for words.

Final recommendation

Please, feel free to read :h hop. It contains everything I just explained and so much more, like Hop extensions, multi windows, etc. Have fun hopping around!

↑ Useful Hop in 2022

hop.nvim