Skip to content

Commit e4da4bb

Browse files
author
Evan Light
committed
Initial rev plus my scroll up and down commands
0 parents  commit e4da4bb

File tree

4 files changed

+671
-0
lines changed

4 files changed

+671
-0
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
doc/tags

‎README.mkd

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# vimux
2+
3+
Easily interact with tmux from vim.
4+
5+
![vimux](https://www.braintreepayments.com/assets-faccd47687/assets/images/blog/vimux3.png)
6+
7+
What inspired me to write vimux was [tslime.vim](https://github.com/kikijump/tslime.vim), 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.
8+
9+
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`.
10+
11+
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.
12+
13+
## Installation
14+
15+
With **[vim-bundle](https://github.com/benmills/vim-bundle)**: `vim-bundle install benmills/vimux`
16+
17+
Otherwise download the latest [tarball](https://github.com/benmills/vimux/tarball/master), extract it and move `plugin/vimux.vim` inside `~/.vim/plugin`. If you're using [pathogen](https://github.com/tpope/vim-pathogen), then move the entire folder extracted from the tarball into `~/.vim/bundle`.
18+
19+
## Platform-specific Plugins
20+
21+
* [vimux-ruby-test](https://github.com/pgr0ss/vimux-ruby-test) a set of commands to easily run ruby tests
22+
* [vimux-cucumber](https://github.com/cloud8421/vimux-cucumber) run Cucumber Features through Vimux
23+
24+
## Usage
25+
26+
The full documentation is available [online](https://raw.github.com/benmills/vimux/master/doc/vimux.txt) and accessible inside vim `:help vimux`

‎doc/vimux.txt

Lines changed: 296 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
1+
*vimux.txt* easily interact with tmux
2+
3+
Vimux
4+
effortless vim and tmux interaction
5+
6+
==============================================================================
7+
CONTENTS *vimux-contents*
8+
9+
1. About............................ |VimuxAbout|
10+
2. Usage ........................... |VimuxUsage|
11+
2.1 .............................. |VimuxPromptCommand|
12+
2.2 .............................. |VimuxRunLastCommand|
13+
2.3 .............................. |VimuxInspectRunner|
14+
2.4 .............................. |VimuxCloseRunner|
15+
2.5 .............................. |VimuxClosePanes|
16+
2.6 .............................. |VimuxInterruptRunner|
17+
2.7 .............................. |VimuxClearRunnerHistory|
18+
3. Misc ............................ |VimuxMisc|
19+
3.1 Example Keybinding............ |VimuxExampleKeybinding|
20+
3.2 Tslime Replacement............ |VimuxTslimeReplacement|
21+
4. Configuration ................... |VimuxConfiguration|
22+
23+
24+
==============================================================================
25+
ABOUT (1) *VimuxAbout*
26+
27+
Vimux -- Easily interact with tmux from vim.
28+
29+
What inspired me to write vimux was tslime.vim [1], a plugin that lets you
30+
send input to tmux. While tslime.vim works well, I felt it wasn't optimized
31+
for my primary use case which was having a smaller tmux pane that I would use
32+
to run tests or play with a REPL.
33+
34+
My goal with vimux is to make interacting with tmux from vim effortless. By
35+
default when you call `VimuxRunCommand` vimux will create a 20% tall
36+
horizontal pane under your current tmux pane and execute a command in it
37+
without losing focus of vim. Once that pane exists whenever you call
38+
`VimuxRunCommand` again the command will be executed in that pane. As I was
39+
using vimux myself I wanted to rerun commands over and over. An example of
40+
this was running the current file through rspec. Rather than typing that over
41+
and over I wrote `VimuxRunLastCommand` that will execute the last command
42+
you called with `VimuxRunCommand`.
43+
44+
Other auxiliary functions and the ones I talked about above can be found
45+
bellow with a full description and example key binds for your vimrc.
46+
47+
[1] https://github.com/kikijump/tslime.vim
48+
49+
50+
==============================================================================
51+
USAGE (2) *VimuxUsage*
52+
53+
The function VimuxRunCommand(command) is the core of Vimux. It will
54+
create a split pane in the current window and run the passed command in it.
55+
>
56+
:call VimuxRunCommand("ls")
57+
<
58+
This will run the command in a split pane without losing focus of vim. If the
59+
command takes a long time to return you can continue to use vim while the
60+
process finishes and will see the output in the pane when it's finished.
61+
62+
Furthermore there are several handy commands all starting with 'Vimux':
63+
- |VimuxRunCommand|
64+
- |VimuxRunLastCommand|
65+
- |VimuxCloseRunner|
66+
- |VimuxClosePanes|
67+
- |VimuxCloseWindows|
68+
- |VimuxInspectRunner|
69+
- |VimuxInterruptRunner|
70+
- |VimuxPromptCommand|
71+
- |VimuxClearRunnerHistory|
72+
73+
74+
Note:
75+
Earlier the all commands had different names. There are still aliases for
76+
convenience. Please chang your configuration according to the new naming
77+
conventions!
78+
79+
The DEPRECATED commands:
80+
- |PromptVimTmuxCommand|
81+
- |RunLastVimTmuxCommand|
82+
- |InspectVimTmuxRunner|
83+
- |CloseVimTmuxRunner|
84+
- |CloseVimTmuxPanes|
85+
- |InterruptVimTmuxRunner|
86+
87+
------------------------------------------------------------------------------
88+
*RunVimTmuxCommand*
89+
*VimuxRunCommand*
90+
VimuxRunCommand~
91+
92+
Run a system command in a small horizontal split bellow
93+
the current pane vim is in. You can optionally pass a second argument to stop
94+
vimux from automatically sending a return after the command.
95+
>
96+
" Run the current file with rspec
97+
map <Leader>rb :call VimuxRunCommand("clear; rspec " . bufname("%"))<CR>
98+
" Run command without sending sending a return
99+
map <Leader>rq :call VimuxRunCommand("clear; rspec " . bufname("%"), 0)<CR>
100+
<
101+
102+
------------------------------------------------------------------------------
103+
*PromptVimTmuxCommand*
104+
*VimuxPromptCommand*
105+
VimuxPromptCommand~
106+
107+
Prompt for a command and run it in a small horizontal split bellow the current
108+
pane.
109+
>
110+
" Prompt for a command to run map
111+
<Leader>vp :VimuxPromptCommand<CR>
112+
<
113+
114+
------------------------------------------------------------------------------
115+
*RunLastVimTmuxCommand*
116+
*VimuxRunLastCommand*
117+
VimuxRunLastCommand~
118+
119+
Run the last command executed by `VimuxRunCommand`
120+
>
121+
" Run last command executed by VimuxRunCommand
122+
map <Leader>vl :VimuxRunLastCommand<CR>
123+
<
124+
125+
------------------------------------------------------------------------------
126+
*InspectVimTmuxRunner*
127+
*VimuxInspectRunner*
128+
VimuxInspectRunner~
129+
130+
Move into the tmux runner pane created by `VimuxRunCommand` and enter copy
131+
pmode (scroll mode).
132+
>
133+
" Inspect runner pane map
134+
<Leader>vi :VimuxInspectRunner<CR>
135+
<
136+
137+
------------------------------------------------------------------------------
138+
*CloseVimTmuxRunner*
139+
*VimuxCloseRunner*
140+
VimuxCloseRunner~
141+
142+
Close the tmux runner created by `VimuxRunCommand`
143+
>
144+
" Close vim tmux runner opened by VimuxRunCommand
145+
map <Leader>vq :VimuxCloseRunner<CR>
146+
<
147+
148+
------------------------------------------------------------------------------
149+
*CloseVimTmuxPanes*
150+
*VimuxClosePanes*
151+
VimuxClosePanes~
152+
153+
Close all other tmux panes in the current window.
154+
>
155+
" Close all other tmux panes in current window
156+
map <Leader>vx :VimuxClosePanes<CR>
157+
>
158+
159+
------------------------------------------------------------------------------
160+
*InterruptVimTmuxRunner*
161+
*VimuxInterruptRunner*
162+
VimuxInterruptRunner~
163+
164+
Interrupt any command that is running inside the
165+
runner pane.
166+
>
167+
" Interrupt any command running in the runner pane map
168+
<Leader>vs :VimuxInterruptRunner<CR>
169+
<
170+
171+
172+
173+
------------------------------------------------------------------------------
174+
*VimuxClearRunnerHistory*
175+
VimuxClearRunnerHistory~
176+
177+
Clear ths tmux history of the runner pane for when
178+
you enter tmux scroll mode inside the runner pane.
179+
>
180+
" Clear the tmux history of the runner pane
181+
<Leader>vc :VimuxClearRunnerHistory<CR>
182+
<
183+
184+
185+
==============================================================================
186+
MISC (3) *VimuxMisc*
187+
188+
------------------------------------------------------------------------------
189+
*VimuxExampleKeybinding*
190+
Full Keybind Example~
191+
192+
>
193+
" Run the current file with rspec
194+
map <Leader>rb :call VimuxRunCommand("clear; rspec " . bufname("%"))<CR>
195+
196+
" Prompt for a command to run
197+
map <Leader>rp :VimuxPromptCommand<CR>
198+
199+
" Run last command executed by VimuxRunCommand
200+
map <Leader>rl :VimuxRunLastCommand<CR>
201+
202+
" Inspect runner pane
203+
map <Leader>ri :VimuxInspectRunner<CR>
204+
205+
" Close all other tmux panes in current window
206+
map <Leader>rx :VimuxClosePanes<CR>
207+
208+
" Close vim tmux runner opened by VimuxRunCommand
209+
map <Leader>rq :VimuxCloseRunner<CR>
210+
211+
" Interrupt any command running in the runner pane
212+
map <Leader>rs :VimuxInterruptRunner<CR>
213+
>
214+
215+
------------------------------------------------------------------------------
216+
*VimuxTslimeReplacement*
217+
Vimux as tslime replacement~
218+
219+
Here is how to use vimux to send code to a REPL. This is similar to tslime.
220+
First, add some helpful mappings.
221+
222+
>
223+
" Prompt for a command to run
224+
map <LocalLeader>vp :VimuxPromptCommand<CR>
225+
226+
" If text is selected, save it in the v buffer and send that buffer it to tmux
227+
vmap <LocalLeader>vs "vy :call VimuxRunCommand(@v . "\n", 0)<CR>
228+
229+
" Select current paragraph and send it to tmux
230+
nmap <LocalLeader>vs vip<LocalLeader>vs<CR>
231+
<
232+
233+
Now, open a clojure file. Let's say your leader is backslash (\). Type \vp,
234+
and then type lein repl at the prompt. This opens a tmux split running a REPL.
235+
Then, select text or put the cursor on a function and type \vs. This will send
236+
it to the REPL and evaluate it. The reason we pass `0` to `VimuxRunCommand`
237+
is to stop the normal return that is sent to the runner pane and use our own
238+
new line so the clojure REPL will evaluate the selected text without adding an
239+
extra return. Thanks to @trptcolin for discovering this issue.
240+
241+
242+
==============================================================================
243+
CONFIGURATION (4) *VimuxConfiguration*
244+
245+
You can configure Vimux like this:
246+
247+
------------------------------------------------------------------------------
248+
*VimuxConfiguration_height*
249+
2.1 g:VimuxHeight~
250+
251+
The percent of the screen the split pane Vimux will spawn should take up.
252+
253+
let g:VimuxHeight = "40"
254+
255+
Default: "20"
256+
257+
------------------------------------------------------------------------------
258+
*VimuxConfiguration_orientation*
259+
2.2 g:VimuxOrientation~
260+
261+
The default orientation of the split tmux pane. This tells tmux to make the
262+
pane either vertically or horizontally, which is backward from how Vim handles
263+
creating splits.
264+
265+
let g:VimuxOrientation = "h"
266+
267+
Options:
268+
"v": vertical
269+
"h": horizontal
270+
271+
Default: "v"
272+
273+
------------------------------------------------------------------------------
274+
*VimuxConfiguration_use_nearest_pane*
275+
2.3 g:VimuxUseNearestPane~
276+
277+
Use exising pane (not used by vim) if found instead of running split-window.
278+
279+
let VimuxUseNearestPane = 1
280+
281+
Default: 0
282+
283+
------------------------------------------------------------------------------
284+
*VimuxConfiguration_reset_sequence*
285+
2.4 g:VimuxResetSequence~
286+
287+
The keys sent to the runner pane before running a command. By default it sends
288+
`q` to make sure the pane is not in scroll-mode and `C-u` to clear the line.
289+
290+
let VimuxUseNearestPane = ""
291+
292+
Default: "q C-u"
293+
294+
295+
==============================================================================
296+
vim:tw=78:ts=2:sw=2:expandtab:ft=help:norl:

0 commit comments

Comments
 (0)