Skip to content

Commit 7f65c9c

Browse files
benmillsbenmills
committed
Merge pull request #21 from sotte/docs
The documentation is now available as vim help.
2 parents 3967826 + c57660b commit 7f65c9c

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)