Skip to content

Commit c57660b

Browse files
sottesotte
committed
The documentation is now available as vim help.
Don't you hate it when you have to leave vim to do something that you could easily do within vim? For example looking up the help for an awesome vim plugin!
1 parent 3967826 commit c57660b

File tree

1 file changed

+202
-12
lines changed

1 file changed

+202
-12
lines changed

‎doc/vimux.txt

Lines changed: 202 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,52 @@
44
effortless vim and tmux interaction
55

66
==============================================================================
7-
CONTENTS *vimux-contents*
7+
CONTENTS *vimux-contents*
8+
9+
1. About............................ |VimuxAbout|
10+
2. Usage ........................... |VimuxUsage|
11+
2.1 .............................. |PromptVimTmuxCommand|
12+
2.2 .............................. |RunLastVimTmuxCommand|
13+
2.3 .............................. |InspectVimTmuxRunner|
14+
2.4 .............................. |CloseVimTmuxRunner|
15+
2.5 .............................. |CloseVimTmuxPanes|
16+
2.6 .............................. |InterruptVimTmuxRunner|
17+
3. Misc ............................ |VimuxMisc|
18+
3.1 Example Keybinding............ |VimuxExampleKeybinding|
19+
3.2 Tslime Replacement............ |VimuxTslimeReplacement|
20+
4. Configuration ................... |VimuxConfiguration|
821

9-
1. Usage ........................... |VimuxUsage|
10-
2. Configuration ................... |VimuxConfiguration|
1122

1223
==============================================================================
13-
1. Usage *VimuxUsage*
24+
ABOUT (1) *VimuxAbout*
25+
26+
Vimux -- Easily interact with tmux from vim.
27+
28+
This project is still in development, so some features are still missing.
29+
30+
What inspired me to write vimux was tslime.vim [1], a plugin that lets you
31+
send input to tmux. While tslime.vim works well, I felt it wasn't optimized
32+
for my primary use case which was having a smaller tmux pane that I would use
33+
to run tests or play with a REPL.
34+
35+
My goal with vimux is to make interacting with tmux from vim effortless. By
36+
default when you call `RunVimTmuxCommand` vimux will create a 20% tall
37+
horizontal pane under your current tmux pane and execute a command in it
38+
without losing focus of vim. Once that pane exists whenever you call
39+
`RunVimTmuxCommand` again the command will be executed in that pane. As I was
40+
using vimux myself I wanted to rerun commands over and over. An example of
41+
this was running the current file through rspec. Rather than typing that over
42+
and over I wrote `RunLastVimTmuxCommand` that will execute the last command
43+
you called with `RunVimTmuxCommand`.
44+
45+
Other auxiliary functions and the ones I talked about above can be found
46+
bellow with a full description and example key binds for your vimrc.
47+
48+
[1] https://github.com/kikijump/tslime.vim
49+
50+
51+
==============================================================================
52+
USAGE (2) *VimuxUsage*
1453

1554
The function RunVimTmuxCommand(command) is the core of Vimux. It will
1655
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.
1958

2059
This will run the command in a split pane without losing focus of vim. If the
2160
command takes a long time to return you can continue to use vim while the
22-
process finishes and will see the output in the pane when it's finished. Check
23-
out http://github.com/benmills/vimux for more information and updates.
61+
process finishes and will see the output in the pane when it's finished.
62+
63+
Furthermore there are several handy commands:
64+
65+
- |PromptVimTmuxCommand|
66+
- |RunLastVimTmuxCommand|
67+
- |InspectVimTmuxRunner|
68+
- |CloseVimTmuxRunner|
69+
- |CloseVimTmuxPanes|
70+
- |InterruptVimTmuxRunner|
71+
72+
------------------------------------------------------------------------------
73+
*RunVimTmuxCommand*
74+
RunVimTmuxCommand~
75+
76+
Run a system command in a small horizontal split bellow
77+
the current pane vim is in. You can optionally pass a second argument to stop
78+
vimux from automatically sending a return after the command.
79+
>
80+
" Run the current file with rspec
81+
map <Leader>rb :call RunVimTmuxCommand("clear; rspec " . bufname("%"))<CR>
82+
" Run command without sending sending a return
83+
map <Leader>rq :call RunVimTmuxCommand("clear; rspec " . bufname("%"), 0)<CR>
84+
<
85+
86+
------------------------------------------------------------------------------
87+
*PromptVimTmuxCommand*
88+
PromptVimTmuxCommand~
89+
90+
Prompt for a command and run it in a small horizontal split bellow the current
91+
pane.
92+
>
93+
" Prompt for a command to run map
94+
<Leader>rp :PromptVimTmuxCommand<CR>
95+
<
96+
97+
------------------------------------------------------------------------------
98+
*RunLastVimTmuxCommand*
99+
RunLastVimTmuxCommand~
100+
101+
Run the last command executed by `RunVimTmuxCommand`
102+
>
103+
" Run last command executed by RunVimTmuxCommand
104+
map <Leader>rl :RunLastVimTmuxCommand<CR>
105+
<
106+
107+
------------------------------------------------------------------------------
108+
*InspectVimTmuxRunner*
109+
InspectVimTmuxRunner~
110+
111+
Move into the tmux runner pane created by `RunVimTmuxCommand` and enter copy
112+
pmode (scroll mode).
113+
>
114+
" Inspect runner pane map
115+
<Leader>ri :InspectVimTmuxRunner<CR>
116+
<
117+
118+
------------------------------------------------------------------------------
119+
*CloseVimTmuxRunner*
120+
CloseVimTmuxRunner~
121+
122+
Close the tmux runner created by `RunVimTmuxCommand`
123+
>
124+
" Close vim tmux runner opened by RunVimTmuxCommand
125+
map <Leader>rq :CloseVimTmuxRunner<CR>
126+
<
127+
128+
------------------------------------------------------------------------------
129+
*CloseVimTmuxPanes*
130+
CloseVimTmuxPanes~
131+
132+
Close all other tmux panes in the current window.
133+
>
134+
" Close all other tmux panes in current window
135+
map <Leader>rx :CloseVimTmuxPanes<CR>
136+
>
137+
138+
------------------------------------------------------------------------------
139+
*InterruptVimTmuxRunner*
140+
InterruptVimTmuxRunner~
141+
142+
Interrupt any command that is running inside the
143+
runner pane.
144+
>
145+
" Interrupt any command running in the runner pane map
146+
<Leader>rs :InterruptVimTmuxRunner<CR>
147+
<
148+
24149

25150
==============================================================================
26-
2. Configuration *VimuxConfiguration*
151+
MISC (3) *VimuxMisc*
152+
153+
------------------------------------------------------------------------------
154+
*VimuxExampleKeybinding*
155+
Full Keybind Example~
27156

28-
These are the available options for Vimux
157+
>
158+
" Run the current file with rspec
159+
map <Leader>rb :call RunVimTmuxCommand("clear; rspec " . bufname("%"))<CR>
160+
161+
" Prompt for a command to run
162+
map <Leader>rp :PromptVimTmuxCommand<CR>
163+
164+
" Run last command executed by RunVimTmuxCommand
165+
map <Leader>rl :RunLastVimTmuxCommand<CR>
166+
167+
" Inspect runner pane
168+
map <Leader>ri :InspectVimTmuxRunner<CR>
169+
170+
" Close all other tmux panes in current window
171+
map <Leader>rx :CloseVimTmuxPanes<CR>
172+
173+
" Close vim tmux runner opened by RunVimTmuxCommand
174+
map <Leader>rq :CloseVimTmuxRunner<CR>
175+
176+
" Interrupt any command running in the runner pane
177+
map <Leader>rs :InterruptVimTmuxRunner<CR>
178+
>
29179
30180
------------------------------------------------------------------------------
31-
2.1 g:VimuxHeight *VimuxConfiguration_height*
181+
*VimuxTslimeReplacement*
182+
Vimux as tslime replacement~
183+
184+
Here is how to use vimux to send code to a REPL. This is similar to tslime.
185+
First, add some helpful mappings.
186+
187+
>
188+
" Prompt for a command to run
189+
map <LocalLeader>vp :PromptVimTmuxCommand<CR>
190+
191+
" If text is selected, save it in the v buffer and send that buffer it to tmux
192+
vmap <LocalLeader>vs "vy :call RunVimTmuxCommand(@v . "\n", 0)<CR>
193+
194+
" Select current paragraph and send it to tmux
195+
nmap <LocalLeader>vs vip<LocalLeader>vs<CR>
196+
<
197+
198+
Now, open a clojure file. Let's say your leader is backslash (\). Type \vp,
199+
and then type lein repl at the prompt. This opens a tmux split running a REPL.
200+
Then, select text or put the cursor on a function and type \vs. This will send
201+
it to the REPL and evaluate it. The reason we pass `0` to `RunVimTmuxCommand`
202+
is to stop the normal return that is sent to the runner pane and use our own
203+
new line so the clojure REPL will evaluate the selected text without adding an
204+
extra return. Thanks to @trptcolin for discovering this issue.
205+
206+
207+
==============================================================================
208+
CONFIGURATION (4) *VimuxConfiguration*
209+
210+
You can configure Vimux like this:
211+
212+
------------------------------------------------------------------------------
213+
*VimuxConfiguration_height*
214+
2.1 g:VimuxHeight~
32215

33216
The percent of the screen the split pane Vimux will spawn should take up.
34217

@@ -37,7 +220,8 @@ The percent of the screen the split pane Vimux will spawn should take up.
37220
Default: "20"
38221

39222
------------------------------------------------------------------------------
40-
2.2 g:VimuxOrientation *VimuxConfiguration_orientation*
223+
*VimuxConfiguration_orientation*
224+
2.2 g:VimuxOrientation~
41225

42226
The default orientation of the split tmux pane. This tells tmux to make the
43227
pane either vertically or horizontally, which is backward from how Vim handles
@@ -52,7 +236,8 @@ Options:
52236
Default: "v"
53237

54238
------------------------------------------------------------------------------
55-
2.3 g:VimuxUseNearestPane *VimuxConfiguration_use_nearest_pane*
239+
*VimuxConfiguration_use_nearest_pane*
240+
2.3 g:VimuxUseNearestPane~
56241

57242
Use exising pane (not used by vim) if found instead of running split-window.
58243

@@ -61,11 +246,16 @@ Use exising pane (not used by vim) if found instead of running split-window.
61246
Default: 0
62247

63248
------------------------------------------------------------------------------
64-
2.4 g:VimuxResetSequence *VimuxConfiguration_reset_sequence*
249+
*VimuxConfiguration_reset_sequence*
250+
2.4 g:VimuxResetSequence~
65251

66252
The keys sent to the runner pane before running a command. By default it sends
67253
`q` to make sure the pane is not in scroll-mode and `C-u` to clear the line.
68254

69255
let VimuxUseNearestPane = ""
70256

71257
Default: "q C-u"
258+
259+
260+
==============================================================================
261+
vim:tw=78:ts=2:sw=2:expandtab:ft=help:norl:

0 commit comments

Comments
 (0)