Harpoon.kak - quickly navigate to your most important files

I created a little plugin called harpoon.kak, based on ThePrimeagen’s Harpoon neovim plugin. There isn’t 1:1 feature parity, in fact, far from it, but the primary feature for which the plugin is named is here, and works well.

A common issue when coding is that you have a handful of files that you’re “actually” working on, but you often end up jumping into other files for quick edits or reference. This causes your jumplist to get cluttered with a bunch of stuff you don’t need, and finding the file you were actually working on becomes a dance of <c-o> and <c-i>. Alternate file works some of the time, but can also get messy if you jump around to much.

harpoon.kak allows you to “harpoon” a file into a list, where you can easily access it again with a simple shortcut. This allows you to keep the handful of files you’re actually working on easily accessible, and jump back to them immediately after following a long string of file jumps.

To harpoon a file, call the :harpoon-add command. Passing a number will add the file to that index in the list, otherwise it will be added to the lowest available slot. You can then call :harpoon-nav <index> to navigate back to that file. You could use these commands as is, but the real magic is when you bind these commands to convenient shortcuts.

The default bindings, which you can add using :harpoon-add-bindings, will add the harpoon user mode to <leader>h and set <c-1> through <c-9> to act as shortcuts to get to the corresponding file in the list. Quickly harpoon a file with <leader>h1, then get back to it at any time with <c-1>.

There are a few other commands. :harpoon-add-or-nav combines the two commands listed previously, so you can add the current file if the slot is empty, or navigate to it if it’s occupied. You can also remove files from the list with :harpoon-remove <index>. :harpoon-list will list your harpoons in an info box.

That’s all the plugin does! I plan on adding a few more things in the future, such as a *harpoons* buffer to view and edit your harpoons, and persisting harpoons per project or session, but the main functionality is complete.

Please let me know what you think!

Installation

You can install the plugin in the usual manner, or using a plugin manager. However, this plugin depends on luar, because bash scripting and I do not get along. Be sure you have Lua itself on your PATH somewhere.

Saving selection states

The Neovim plugin saves the current selections when you harpoon a file, so it restores them when you re-open the file. However, I feel that is out of scope for the kak equivalent. If you wish to preserve selections, Screwtape’s excellent kakoune-state-save plugin will do that for you.

5 Likes

This is really cool! It’s actually a lot like my own plugin filelist.kak

This plugin no longer depends on luar. Now that I know some basic shell scripting, I was able to re-implement it fairly easily. I also improved the docstrings and kakscript formatting somewhat.

:harpoon-add-or-nav was removed in favor of adding a <add-if-empty> parameter to :harpoon-nav. Pass true and it will add the harpoon if it doesn’t exist.