@ -4,13 +4,52 @@
effortless vim and tmux interaction
==============================================================================
CONTENTS *vimux-contents*
CONTENTS *vimux-contents*
1. About............................ |VimuxAbout|
2. Usage ........................... |VimuxUsage|
2.1 .............................. |PromptVimTmuxCommand|
2.2 .............................. |RunLastVimTmuxCommand|
2.3 .............................. |InspectVimTmuxRunner|
2.4 .............................. |CloseVimTmuxRunner|
2.5 .............................. |CloseVimTmuxPanes|
2.6 .............................. |InterruptVimTmuxRunner|
3. Misc ............................ |VimuxMisc|
3.1 Example Keybinding............ |VimuxExampleKeybinding|
3.2 Tslime Replacement............ |VimuxTslimeReplacement|
4. Configuration ................... |VimuxConfiguration|
1. Usage ........................... |VimuxUsage|
2. Configuration ................... |VimuxConfiguration|
==============================================================================
1. Usage *VimuxUsage*
ABOUT (1) *VimuxAbout*
Vimux -- Easily interact with tmux from vim.
This project is still in development, so some features are still missing.
What inspired me to write vimux was tslime.vim [1], a plugin that lets you
send input to tmux. While tslime.vim works well, I felt it wasn't optimized
for my primary use case which was having a smaller tmux pane that I would use
to run tests or play with a REPL.
My goal with vimux is to make interacting with tmux from vim effortless. By
default when you call `RunVimTmuxCommand` vimux will create a 20% tall
horizontal pane under your current tmux pane and execute a command in it
without losing focus of vim. Once that pane exists whenever you call
`RunVimTmuxCommand` again the command will be executed in that pane. As I was
using vimux myself I wanted to rerun commands over and over. An example of
this was running the current file through rspec. Rather than typing that over
and over I wrote `RunLastVimTmuxCommand` that will execute the last command
you called with `RunVimTmuxCommand`.
Other auxiliary functions and the ones I talked about above can be found
bellow with a full description and example key binds for your vimrc.
[1] https://github.com/kikijump/tslime.vim
==============================================================================
USAGE (2) *VimuxUsage*
The function RunVimTmuxCommand(command) is the core of Vimux. It will
create a split pane in the current window and run the passed command in it.
@ -19,16 +58,160 @@ create a split pane in the current window and run the passed command in it.
This will run the command in a split pane without losing focus of vim. If the
command takes a long time to return you can continue to use vim while the
process finishes and will see the output in the pane when it's finished. Check
out http://github.com/benmills/vimux for more information and updates.
process finishes and will see the output in the pane when it's finished.
Furthermore there are several handy commands:
- |PromptVimTmuxCommand|
- |RunLastVimTmuxCommand|
- |InspectVimTmuxRunner|
- |CloseVimTmuxRunner|
- |CloseVimTmuxPanes|
- |InterruptVimTmuxRunner|
------------------------------------------------------------------------------
*RunVimTmuxCommand*
RunVimTmuxCommand~
Run a system command in a small horizontal split bellow
the current pane vim is in. You can optionally pass a second argument to stop
vimux from automatically sending a return after the command.
>
" Run the current file with rspec
map <Leader>rb :call RunVimTmuxCommand("clear; rspec " . bufname("%"))<CR>
" Run command without sending sending a return
map <Leader>rq :call RunVimTmuxCommand("clear; rspec " . bufname("%"), 0)<CR>
<
------------------------------------------------------------------------------
*PromptVimTmuxCommand*
PromptVimTmuxCommand~
Prompt for a command and run it in a small horizontal split bellow the current
pane.
>
" Prompt for a command to run map
<Leader>rp :PromptVimTmuxCommand<CR>
<
------------------------------------------------------------------------------
*RunLastVimTmuxCommand*
RunLastVimTmuxCommand~
Run the last command executed by `RunVimTmuxCommand`
>
" Run last command executed by RunVimTmuxCommand
map <Leader>rl :RunLastVimTmuxCommand<CR>
<
------------------------------------------------------------------------------
*InspectVimTmuxRunner*
InspectVimTmuxRunner~
Move into the tmux runner pane created by `RunVimTmuxCommand` and enter copy
pmode (scroll mode).
>
" Inspect runner pane map
<Leader>ri :InspectVimTmuxRunner<CR>
<
------------------------------------------------------------------------------
*CloseVimTmuxRunner*
CloseVimTmuxRunner~
Close the tmux runner created by `RunVimTmuxCommand`
>
" Close vim tmux runner opened by RunVimTmuxCommand
map <Leader>rq :CloseVimTmuxRunner<CR>
<
------------------------------------------------------------------------------
*CloseVimTmuxPanes*
CloseVimTmuxPanes~
Close all other tmux panes in the current window.
>
" Close all other tmux panes in current window
map <Leader>rx :CloseVimTmuxPanes<CR>
>
------------------------------------------------------------------------------
*InterruptVimTmuxRunner*
InterruptVimTmuxRunner~
Interrupt any command that is running inside the
runner pane.
>
" Interrupt any command running in the runner pane map
<Leader>rs :InterruptVimTmuxRunner<CR>
<
==============================================================================
2. Configuration *VimuxConfiguration*
MISC (3) *VimuxMisc*
------------------------------------------------------------------------------
*VimuxExampleKeybinding*
Full Keybind Example~
These are the available options for Vimux
>
" Run the current file with rspec
map <Leader>rb :call RunVimTmuxCommand("clear; rspec " . bufname("%"))<CR>
" Prompt for a command to run
map <Leader>rp :PromptVimTmuxCommand<CR>
" Run last command executed by RunVimTmuxCommand
map <Leader>rl :RunLastVimTmuxCommand<CR>
" Inspect runner pane
map <Leader>ri :InspectVimTmuxRunner<CR>
" Close all other tmux panes in current window
map <Leader>rx :CloseVimTmuxPanes<CR>
" Close vim tmux runner opened by RunVimTmuxCommand
map <Leader>rq :CloseVimTmuxRunner<CR>
" Interrupt any command running in the runner pane
map <Leader>rs :InterruptVimTmuxRunner<CR>
>
------------------------------------------------------------------------------
2.1 g:VimuxHeight *VimuxConfiguration_height*
*VimuxTslimeReplacement*
Vimux as tslime replacement~
Here is how to use vimux to send code to a REPL. This is similar to tslime.
First, add some helpful mappings.
>
" Prompt for a command to run
map <LocalLeader>vp :PromptVimTmuxCommand<CR>
" If text is selected, save it in the v buffer and send that buffer it to tmux
vmap <LocalLeader>vs "vy :call RunVimTmuxCommand(@v . "\n", 0)<CR>
" Select current paragraph and send it to tmux
nmap <LocalLeader>vs vip<LocalLeader>vs<CR>
<
Now, open a clojure file. Let's say your leader is backslash (\). Type \vp,
and then type lein repl at the prompt. This opens a tmux split running a REPL.
Then, select text or put the cursor on a function and type \vs. This will send
it to the REPL and evaluate it. The reason we pass `0` to `RunVimTmuxCommand`
is to stop the normal return that is sent to the runner pane and use our own
new line so the clojure REPL will evaluate the selected text without adding an
extra return. Thanks to @trptcolin for discovering this issue.
==============================================================================
CONFIGURATION (4) *VimuxConfiguration*
You can configure Vimux like this:
------------------------------------------------------------------------------
*VimuxConfiguration_height*
2.1 g:VimuxHeight~
The percent of the screen the split pane Vimux will spawn should take up.
@ -37,7 +220,8 @@ The percent of the screen the split pane Vimux will spawn should take up.
Default: "20"
------------------------------------------------------------------------------
2.2 g:VimuxOrientation *VimuxConfiguration_orientation*
*VimuxConfiguration_orientation*
2.2 g:VimuxOrientation~
The default orientation of the split tmux pane. This tells tmux to make the
pane either vertically or horizontally, which is backward from how Vim handles
@ -52,7 +236,8 @@ Options:
Default: "v"
------------------------------------------------------------------------------
2.3 g:VimuxUseNearestPane *VimuxConfiguration_use_nearest_pane*
*VimuxConfiguration_use_nearest_pane*
2.3 g:VimuxUseNearestPane~
Use exising pane (not used by vim) if found instead of running split-window.
@ -61,7 +246,8 @@ Use exising pane (not used by vim) if found instead of running split-window.
Default: 0
------------------------------------------------------------------------------
2.4 g:VimuxResetSequence *VimuxConfiguration_reset_sequence*
*VimuxConfiguration_reset_sequence*
2.4 g:VimuxResetSequence~
The keys sent to the runner pane before running a command. By default it sends
`q` to make sure the pane is not in scroll-mode and `C-u` to clear the line.
@ -69,3 +255,7 @@ The keys sent to the runner pane before running a command. By default it sends
let VimuxUseNearestPane = ""
Default: "q C-u"
==============================================================================
vim:tw=78:ts=2:sw=2:expandtab:ft=help:norl:
Stefan Otte
12 years ago