From 5190f6f9fc0c9c5c3c54f9e802c54735078c2551 Mon Sep 17 00:00:00 2001 From: ThePrimeagen Date: Wed, 14 Apr 2021 08:23:46 -0600 Subject: [PATCH] feat(readme): First update to the readme --- README.md | 146 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 140 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index bdee86f..63c4cbf 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # WARNING -This is still beta. We are getting there, but its not as fast as I would like. -Therefore APIs are subject to change. +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 a ticket! ![Harpoon](harpoon.png) -- Image provided by Liberty_DevCap @@ -14,9 +15,16 @@ yourself frequenting a small set of files (maybe it depends on task) and you are tired of using a fuzzy finder, :bnext/prev, alternate file doesn't quite cut it, etc etc. +## The Other Problem +You want to execute some project specific commands or have any number of +persistent terminals that can be easily navigated to. + ## The Solution The ability to specify, or on the fly, mark and create persisting key strokes -to go to the files you want. This includes terminal navigation. +to go to the files you want. + +## The Other Solution +Unlimited terminals and navigation. ## Installation Simply install via your favorite plugin manager. @@ -26,12 +34,138 @@ Plug 'ThePrimeagen/harpoon' ``` ## Harpooning -TO BE DETERMINED +There are two modes of harpoon. File navigation and terminal navigation. +Setup of harpoon configuration is at the bottom since its for more advanced use +cases. +### File Navigation +#### Mark a file +Marking a file is similar to vim global marks, but differ in a few key ways. -Check out +* They auto update their position +* They are unique _per project_. +* They can be hand edited vs replaced (swapping is easier) + +To mark a file simply call the following lua function ```lua -// TODO: Fill this also in you pleb +:lua require("harpoon.mark").add_file() ``` +This will mark the file and add it to the end of the mark list. + +#### Navigate to file +To navigate to any of the marked files simply call the navigation function with +which index. + +```lua +:lua require("harpoon.ui").nav_file(3) -- This will navigate to file 3 +``` + +#### Manipulating current marks +There is a quick menu that will allow for you to edit your marks. You can hand +edit the name, its position within the list, or remove it from the list. To +bring up the quick list execute the following lua command. + +```lua +:lua require("harpoon.ui").toggle_quick_menu() +``` + +You can simply edit this list as if it were a document in vim. `:wq` to save +the new edits or `:q` to ignore the edits. There is to save upon call to +toggle if you prefer that way. + +### Terminal Navigation +#### Motivation for terminals in neovim +I want to use the terminal since I can gF and 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). + +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. + +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). + +#### Navigating to a terminal +To navigate to a terminal simply provide an index and it will go. If there is +no terminal in that index or the terminal has been closed by some means, +harpoon will create a new terminal at that location. + +```lua +lua require("harpoon.term").gotoTerminal(1) +``` + +You can provide as high of a number as you would like. There is no terminal +count limitation though I personally find anything beyond two oft confusing. + +#### Commands to terminal +Sometimes you wish to send commands to terminals that have been preconfigured +for a project. To make this work properly you must predefine a command or hard +code it as part of the send process. + +```lua +" This will send to terminal 1 either the predefined command 1 in the terminal +" config or "ls -la" +lua require("harpoon.term").sendCommand(1, 1) +lua require("harpoon.term").sendCommand(1, "ls -la") +``` + +### Setup +Setup should be called once. + +#### TODO: Make this callable more than once and just layer in the commands +Yes... A todo in a readme. Deal with it. + +#### The Configuration File +You can configure harpoon via lua in your rc. Here is a simple example that +will add a specific command to a project. + +##### Global Settings + +```lua +Here is the set of global settings and their default values. + +require("harpoon").setup({ + global_settings = { + save_on_toggle = false + }, + ... your other configs ... +}) +``` + +#### Preconfigured Terminal Commands +These are project specific commands that you wish to execute on the regular. + +```lua +require("harpoon").setup({ + projects = { + -- Yes $HOME works + ["$HOME/personal/vim-with-me/server"] = { + term = { + cmds = { + "./env && npx ts-node src/index.ts" + } + } + }, + + -- This uses the wildcard api, you can check it out via branch wildcards + -- not quite ready yet for mainline. + -- Wildcards are to be used in conjunction with git worktrees (at least + -- that is my goal) + ["/home/theprimeagen/personal/harpoon/{}"] = { + term = { + cmds = { + "echo hello {}" + } + }, + }, + +``` + + +