mirror of
https://github.com/ThePrimeagen/harpoon.git
synced 2025-07-14 10:00:29 +00:00
feat: more tests, slowly updating readme
This commit is contained in:
mpaulson
parent
5471588300
commit
f84bf553e0
190
README.md
190
README.md
@ -10,27 +10,32 @@
|
||||
|
||||
-- image provided by **Bob Rust**
|
||||
|
||||
## ⇁ TOC
|
||||
[Note to legacy Harpoon 1 users](/#Note%20to%20legacy%20Harpoon%201%20users)
|
||||
[The Problems:](/#The%20Problems:)
|
||||
[ The Solutions:](/#%20The%20Solutions:)
|
||||
[Installation](/#Installation)
|
||||
[Getting Started](/#Getting%20Started)
|
||||
[Social](/#Social)
|
||||
|
||||
## ⇁ WIP
|
||||
This is not fully baked, though used by several people. If you experience any
|
||||
issues, see some improvement you think would be amazing, or just have some
|
||||
feedback for harpoon (or me), make an issue!
|
||||
## ⇁ Note to legacy Harpoon 1 users
|
||||
Original Harpoon will remain in a frozen state and i will merge PRs in with _no
|
||||
code review_ for those that wish to remain on that. Harpoon 2 is significantly
|
||||
better and allows for MUCH greater control. Please migrate to that (will
|
||||
become `master` within the next few months).
|
||||
|
||||
|
||||
## ⇁ The Problems:
|
||||
## ⇁ The Problems
|
||||
1. You're working on a codebase. medium, large, tiny, whatever. You find
|
||||
yourself 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.
|
||||
1. You want to execute some project specific commands or have any number of
|
||||
persistent terminals that can be easily navigated to.
|
||||
|
||||
|
||||
## ⇁ The Solutions:
|
||||
## ⇁ The Solutions
|
||||
1. The ability to specify, or on the fly, mark and create persisting key strokes
|
||||
to go to the files you want.
|
||||
1. Unlimited terminals and navigation.
|
||||
|
||||
|
||||
## ⇁ Installation
|
||||
* neovim 0.5.0+ required
|
||||
* install using your favorite plugin manager (`vim-plug` in this example)
|
||||
@ -39,173 +44,10 @@ Plug 'nvim-lua/plenary.nvim' " don't forget to add this one if you don't have it
|
||||
Plug 'ThePrimeagen/harpoon'
|
||||
```
|
||||
|
||||
## ⇁ Harpooning
|
||||
here we'll explain how to wield the power of the harpoon:
|
||||
|
||||
|
||||
### Marks
|
||||
you mark files you want to revisit later on
|
||||
```lua
|
||||
:lua require("harpoon.mark").add_file()
|
||||
```
|
||||
|
||||
### File Navigation
|
||||
view all project marks with:
|
||||
```lua
|
||||
:lua require("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
|
||||
```lua
|
||||
:lua require("harpoon.ui").nav_file(3) -- navigates to file 3
|
||||
```
|
||||
you can also cycle the list in both directions
|
||||
```lua
|
||||
:lua require("harpoon.ui").nav_next() -- navigates to next mark
|
||||
:lua require("harpoon.ui").nav_prev() -- navigates to previous mark
|
||||
```
|
||||
|
||||
### Terminal Navigation
|
||||
this works like file navigation except that if there is no terminal at the specified index
|
||||
a new terminal is created.
|
||||
```lua
|
||||
lua require("harpoon.term").gotoTerminal(1) -- navigates to term 1
|
||||
```
|
||||
|
||||
### Commands to Terminals
|
||||
commands can be sent to any terminal
|
||||
```lua
|
||||
lua require("harpoon.term").sendCommand(1, "ls -La") -- sends ls -La to tmux window 1
|
||||
```
|
||||
further more commands can be stored for later quick
|
||||
```lua
|
||||
lua require('harpoon.cmd-ui').toggle_quick_menu() -- shows the commands menu
|
||||
lua require("harpoon.term").sendCommand(1, 1) -- sends command 1 to term 1
|
||||
```
|
||||
|
||||
### Tmux Support
|
||||
tmux is supported out of the box and can be used as a drop-in replacement to normal terminals
|
||||
by simply switching `'term' with 'tmux'` like so
|
||||
|
||||
```lua
|
||||
lua require("harpoon.tmux").gotoTerminal(1) -- goes to the first tmux window
|
||||
lua require("harpoon.tmux").sendCommand(1, "ls -La") -- sends ls -La to tmux window 1
|
||||
lua require("harpoon.tmux").sendCommand(1, 1) -- sends command 1 to tmux window 1
|
||||
```
|
||||
|
||||
`sendCommand` and `goToTerminal` also accept any valid [tmux pane identifier](https://man7.org/linux/man-pages/man1/tmux.1.html#COMMANDS).
|
||||
```lua
|
||||
lua require("harpoon.tmux").gotoTerminal("{down-of}") -- focus the pane directly below
|
||||
lua require("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 a
|
||||
little bash script that will switch to the window which is running neovim.
|
||||
|
||||
In your `tmux.conf` (or anywhere you have keybinds), add this
|
||||
```bash
|
||||
bind-key -r G run-shell "path-to-harpoon/harpoon/scripts/tmux/switch-back-to-nvim"
|
||||
```
|
||||
|
||||
### Telescope Support
|
||||
1st register harpoon as a telescope extension
|
||||
```lua
|
||||
require("telescope").load_extension('harpoon')
|
||||
```
|
||||
currently only marks are supported in telescope
|
||||
```
|
||||
:Telescope harpoon marks
|
||||
```
|
||||
|
||||
## ⇁ Configuration
|
||||
if configuring harpoon is desired it must be done through harpoons setup function
|
||||
```lua
|
||||
require("harpoon").setup({ ... })
|
||||
```
|
||||
|
||||
### Global Settings
|
||||
here are all the available global settings with their default values
|
||||
```lua
|
||||
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 repository
|
||||
mark_branch = false,
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### Preconfigured Terminal Commands
|
||||
to preconfigure terminal commands for later use
|
||||
```lua
|
||||
projects = {
|
||||
-- Yes $HOME works
|
||||
["$HOME/personal/vim-with-me/server"] = {
|
||||
term = {
|
||||
cmds = {
|
||||
"./env && npx ts-node src/index.ts"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## ⇁ Logging
|
||||
- logs are written to `harpoon.log` within the nvim cache path (`:echo stdpath("cache")`)
|
||||
- available log levels are `trace`, `debug`, `info`, `warn`, `error`, or `fatal`. `warn` is default
|
||||
- log level can be set with `vim.g.harpoon_log_level` (must be **before** `setup()`)
|
||||
- launching nvim with `HARPOON_LOG=debug nvim` takes precedence over `vim.g.harpoon_log_level`.
|
||||
- invalid values default back to `warn`.
|
||||
|
||||
## ⇁ Others
|
||||
#### How do Harpoon marks differ from vim global marks
|
||||
they serve a similar purpose however harpoon marks differ in a few key ways:
|
||||
1. They auto update their position within the file
|
||||
1. They are saved _per project_.
|
||||
1. They can be hand edited vs replaced (swapping is easier)
|
||||
|
||||
#### The Motivation behind Harpoon terminals
|
||||
1. I want to use the terminal since I can gF and <c-w>gF to any errors arising
|
||||
from execution that are within the terminal that are not appropriate for
|
||||
something like dispatch. (not just running tests but perhaps a server that runs
|
||||
for X amount of time before crashing).
|
||||
1. I want the terminal to be persistent and I can return to one of many terminals
|
||||
with some finger wizardry and reparse any of the execution information that was
|
||||
not necessarily error related.
|
||||
1. I would like to have commands that can be tied to terminals and sent them
|
||||
without much thinking. Some sort of middle ground between vim-test and just
|
||||
typing them into a terminal (configuring netflix's television project isn't
|
||||
quite building and there are tons of ways to configure).
|
||||
|
||||
#### Use a dynamic width for the Harpoon popup menu
|
||||
Sometimes the default width of `60` is not wide enough.
|
||||
The following example demonstrates how to configure a custom width by setting
|
||||
the menu's width relative to the current window's width.
|
||||
|
||||
```lua
|
||||
require("harpoon").setup({
|
||||
menu = {
|
||||
width = vim.api.nvim_win_get_width(0) - 4,
|
||||
}
|
||||
})
|
||||
```
|
||||
## ⇁ Getting Started
|
||||
|
||||
## ⇁ Social
|
||||
For questions about Harpoon, there's a #harpoon channel on [the Primagen's Discord](https://discord.gg/theprimeagen) server.
|
||||
For questions about Harpoon, there's a #harpoon channel on [the Primagen's Discord](https://discord.gg/theprimeagen) server.
|
||||
* [Discord](https://discord.gg/theprimeagen)
|
||||
* [Twitch](https://www.twitch.tv/theprimeagen)
|
||||
* [Twitter](https://twitter.com/ThePrimeagen)
|
||||
|
||||
@ -55,4 +55,19 @@ describe("harpoon", function()
|
||||
eq(list:length(), 4)
|
||||
eq(list:display(), created_files)
|
||||
end)
|
||||
|
||||
it("edit ui but toggle should not save", function()
|
||||
local list = harpoon:list()
|
||||
local created_files = utils.fill_list_with_files(3, list)
|
||||
|
||||
eq(list:length(), 3)
|
||||
|
||||
harpoon.ui:toggle_quick_menu(list)
|
||||
Buffer.set_contents(harpoon.ui.bufnr, {})
|
||||
harpoon.ui:toggle_quick_menu()
|
||||
|
||||
eq(list:length(), 3)
|
||||
eq(created_files, list:display())
|
||||
|
||||
end)
|
||||
end)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user