Repository files navigation

-- image provided byBob Rust

This is not fully baked, though used by several people. If you experience anyissues, see some improvement you think would be amazing, or just have somefeedback for harpoon (or me), make an issue!

1. You're working on a codebase. medium, large, tiny, whatever. You findyourself frequenting a small set of files and you are tired of using a fuzzy finder,:bnext &:bprev are getting too repetitive, alternate file doesn't quite cut it, etc etc.
2. You want to execute some project specific commands or have any number ofpersistent terminals that can be easily navigated to.

1. The ability to specify, or on the fly, mark and create persisting key strokesto go to the files you want.
2. Unlimited terminals and navigation.

• neovim 0.5.0+ required
• install using your favorite plugin manager (vim-plug in this example)

Plug'nvim-lua/plenary.nvim'" don't forget to add this one if you don't have it yet!Plug'ThePrimeagen/harpoon'

here we'll explain how to wield the power of the harpoon:

you mark files you want to revisit later on

:luarequire("harpoon.mark").add_file()

view all project marks with:

:luarequire("harpoon.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 also can switch to any mark without bringing up the menu, use the below with the desired mark index

:luarequire("harpoon.ui").nav_file(3)-- navigates to file 3

you can also cycle the list in both directions

:luarequire("harpoon.ui").nav_next()-- navigates to next mark:luarequire("harpoon.ui").nav_prev()-- navigates to previous mark

from the quickmenu, open a file in:a vertical split with control+v,a horizontal split with control+x,a new tab with control+t

this works like file navigation except that if there is no terminal at the specified indexa new terminal is created.

luarequire("harpoon.term").gotoTerminal(1)-- navigates to term 1

commands can be sent to any terminal

luarequire("harpoon.term").sendCommand(1,"ls -La")-- sends ls -La to tmux window 1

further more commands can be stored for later quick

luarequire('harpoon.cmd-ui').toggle_quick_menu()-- shows the commands menuluarequire("harpoon.term").sendCommand(1,1)-- sends command 1 to term 1

tmux is supported out of the box and can be used as a drop-in replacement to normal terminalsby simply switching'term' with 'tmux' like so

luarequire("harpoon.tmux").gotoTerminal(1)-- goes to the first tmux windowluarequire("harpoon.tmux").sendCommand(1,"ls -La")-- sends ls -La to tmux window 1luarequire("harpoon.tmux").sendCommand(1,1)-- sends command 1 to tmux window 1

sendCommand andgoToTerminal also accept any validtmux pane identifier.

luarequire("harpoon.tmux").gotoTerminal("{down-of}")-- focus the pane directly belowluarequire("harpoon.tmux").sendCommand("%3","ls")-- send a command to the pane with id '%3'

Once you switch to a tmux window you can always switch back to neovim, this is alittle bash script that will switch to the window which is running neovim.

In yourtmux.conf (or anywhere you have keybinds), add this

bind-key -r G run-shell"path-to-harpoon/harpoon/scripts/tmux/switch-back-to-nvim"

1st register harpoon as a telescope extension

require("telescope").load_extension('harpoon')

currently only marks are supported in telescope

:Telescope harpoon marks

if configuring harpoon is desired it must be done through harpoons setup function

require("harpoon").setup({... })

here are all the available global settings with their default values

global_settings= {-- sets the marks upon calling `toggle` on the ui, instead of require `:w`.save_on_toggle=false,-- saves the harpoon file upon every change. disabling is unrecommended.save_on_change=true,-- sets harpoon to run the command immediately as it's passed to the terminal when calling `sendCommand`.enter_on_sendcmd=false,-- closes any tmux windows harpoon that harpoon creates when you close Neovim.tmux_autoclose_windows=false,-- filetypes that you want to prevent from adding to the harpoon list menu.excluded_filetypes= {"harpoon"},-- set marks specific to each git branch inside git repositorymark_branch=false,-- enable tabline with harpoon markstabline=false,tabline_prefix="",tabline_suffix="",}

to preconfigure terminal commands for later use

projects= {-- Yes $HOME works    ["$HOME/personal/vim-with-me/server"]= {term= {cmds= {"./env && npx ts-node src/index.ts"            }        }    }}

• logs are written toharpoon.log within the nvim cache path (:echo stdpath("cache"))
• available log levels aretrace,debug,info,warn,error, orfatal.warn is default
• log level can be set withvim.g.harpoon_log_level (must bebeforesetup())
• launching nvim withHARPOON_LOG=debug nvim takes precedence overvim.g.harpoon_log_level.
• invalid values default back towarn.

they serve a similar purpose however harpoon marks differ in a few key ways:

1. They auto update their position within the file
2. They are savedper project.
3. They can be hand edited vs replaced (swapping is easier)

1. I want to use the terminal since I can gF and gF to any errors arisingfrom execution that are within the terminal that are not appropriate forsomething like dispatch. (not just running tests but perhaps a server that runsfor X amount of time before crashing).
2. I want the terminal to be persistent and I can return to one of many terminalswith some finger wizardry and reparse any of the execution information that wasnot necessarily error related.
3. I would like to have commands that can be tied to terminals and sent themwithout much thinking. Some sort of middle ground between vim-test and justtyping them into a terminal (configuring netflix's television project isn'tquite building and there are tons of ways to configure).

Sometimes the default width of60 is not wide enough.The following example demonstrates how to configure a custom width by settingthe menu's width relative to the current window's width.

require("harpoon").setup({menu= {width=vim.api.nvim_win_get_width(0)-4,    }})

By default, the tabline will use the default theme of your theme. You can customize by editing the following highlights:

• HarpoonInactive
• HarpoonActive
• HarpoonNumberActive
• HarpoonNumberInactive

Example to make it cleaner:

vim.cmd('highlight! HarpoonInactive guibg=NONE guifg=#63698c')vim.cmd('highlight! HarpoonActive guibg=NONE guifg=white')vim.cmd('highlight! HarpoonNumberActive guibg=NONE guifg=#7aa2f7')vim.cmd('highlight! HarpoonNumberInactive guibg=NONE guifg=#7aa2f7')vim.cmd('highlight! TabLineFill guibg=NONE guifg=white')

Result:

For questions about Harpoon, there's a #harpoon channel onthe Primeagen's Discord server.

• Discord
• Twitch
• Twitter