Introduction

Neovim harpoon plugin, but only the core bits.

Many thanks to ThePrimeagen, this implementation takes many ideas from the original harpoon plugin, as well as various naming conventions for the commonly used publically exposed methods.

The idea is I like all the file marking and switch logic that's part of harpoon, but am not interested in all of the TMUX / terminal stuff.

Looks like ThePrimeagen expresses some similar thoughts based on: issue-255.

There are pretty large changes in this implementation so mapping the 2 outside of what is available publically is not straightforward.

Features

• Supports running multiple different projects at the same time without losing any changes to your marked files.
• Invalid marks get filtered out, only valid changes propagate to marks.
• Marking files at a branch granularity if mark_branch option is set.
• Will set active window to specified file if it is already open rather than opening another window if use_existing option is set, works across tabs.
• Supports storing and using last cursor position if use_cursor option is set.
• Supports different default actions when opening a mark with default_action option.
• A migration script to move existing harpoon marks over.

Limitations

• Having the same project open in multiple instances of Neovim will cause changes to your marked files to get clobbered.

Differences from Original

While many of the publically exposed behaviors have been copied to be nearly exact there are a couple of intentional differences in behavior:

• Invalid files are never saved to your marks. When editing you can add whatever lines you want to the preview, but if it doesn't point to an actual file it'll be thrown out immediately and never persisted. This will also happen if you later delete a file after the first time you open the preview window.
• As a consequence of the above empty lines are also not allowed. Though there may be some value in having your shortcuts remain consistent even when some file is removed this implementation avoids having placeholder slots that need special handling.
• Minor other changes and bug fixes such as 218.

Install

lazy.nvim

{
    'MeanderingProgrammer/harpoon-core.nvim',
    config = function()
        require('harpoon-core').setup({})
    end,
}

Setup

Below is the configuration that gets used by default, any part of it can be modified by the user.

require('harpoon-core').setup({
    -- Make existing window active rather than creating a new window
    use_existing = true,
    -- Default action when opening a mark, defaults to current window
    -- Example: 'vs' will open in new vertical split, 'tabnew' will open in new tab
    default_action = nil,
    -- Set marks specific to each git branch inside git repository
    mark_branch = false,
    -- Use the previous cursor position of marked files when opened
    use_cursor = true,
    -- Settings for popup window
    menu = { width = 60, height = 10 },
    -- Controls confirmation when deleting mark in telescope
    delete_confirmation = true,
})

Migrate Harpoon Marks

This can be done by executing the import_harpoon script: python3 scripts/import_harpoon.py

This requires python to be installed but does not rely on any additional libraries.

Harpooning

This section is a copy paste from the original, with some minor changes / additions.

You can see an example config which assigns all of these commands to keymaps here.

Here we'll explain how to wield the power of the harpoon.

Marks

Adding

You mark files you want to revisit later on.

:lua require('harpoon-core.mark').add_file()

Removing

These can also be removed.

:lua require('harpoon-core.mark').rm_file()

File Navigation

View all project marks.

:lua require('harpoon-core.ui').toggle_quick_menu()

You can go up and down the list, enter, delete or reorder. q and <esc> exit and save the menu.

You can also switch to any mark without bringing up the menu. Below example uses 3 as the target file.

:lua require('harpoon-core.ui').nav_file(3)

You can also cycle the list in both directions.

:lua require('harpoon-core.ui').nav_next()
:lua require('harpoon-core.ui').nav_prev()

From the quickmenu, open a file in:

• Vertical split with <ctrl-v>
• Horizontal split with <ctrl-x>
• New tab with <ctrl-t>

Telescope Support

First register harpoon as a telescope extension.

require('telescope').load_extension('harpoon-core')

Then open the marks page.

Telescope harpoon-core marks

Valid keymaps in Telescope are:

• <ctrl-d> delete the current mark
• <ctrl-p> move mark up one position
• <ctrl-n> move mark down one position