vimux/doc/vimux.txt

*vimux.txt*   easily interact with tmux

                                  Vimux
                   effortless vim and tmux interaction

==============================================================================
CONTENTS                                                        *vimux-contents*

    1. About............................ |VimuxAbout|
    2. Usage ........................... |VimuxUsage|
      2.1 .............................. |VimuxPromptCommand|
      2.2 .............................. |VimuxRunLastCommand|
      2.3 .............................. |VimuxInspectRunner|
      2.4 .............................. |VimuxCloseRunner|
      2.5 .............................. |VimuxClosePanes|
      2.6 .............................. |VimuxInterruptRunner|
      2.7 .............................. |VimuxClearRunnerHistory|
    3. Misc ............................ |VimuxMisc|
      3.1 Example Keybinding............ |VimuxExampleKeybinding|
      3.2 Tslime Replacement............ |VimuxTslimeReplacement|
    4. Configuration ................... |VimuxConfiguration|


==============================================================================
ABOUT (1)                                                           *VimuxAbout*

Vimux -- Easily interact with tmux from vim.

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 `VimuxRunCommand` 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
`VimuxRunCommand` 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 `VimuxRunLastCommand` that will execute the last command
you called with `VimuxRunCommand`.

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 VimuxRunCommand(command) is the core of Vimux. It will
create a split pane in the current window and run the passed command in it.
>
    :call VimuxRunCommand("ls")
<
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.

Furthermore there are several handy commands all starting with 'Vimux':
  - |VimuxRunCommand|
  - |VimuxSendText|
  - |VimuxSendKeys|
  - |VimuxOpenPane|
  - |VimuxRunLastCommand|
  - |VimuxCloseRunner|
  - |VimuxClosePanes|
  - |VimuxCloseWindows|
  - |VimuxInspectRunner|
  - |VimuxInterruptRunner|
  - |VimuxPromptCommand|
  - |VimuxClearRunnerHistory|

------------------------------------------------------------------------------
                                                               *VimuxRunCommand*
VimuxRunCommand~

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 VimuxRunCommand("clear; rspec " . bufname("%"))<CR>
 " Run command without sending a return
 map <Leader>rq :call VimuxRunCommand("clear; rspec " . bufname("%"), 0)<CR>
<

------------------------------------------------------------------------------
                                                               *VimuxSendText*
VimuxSendText~

Send raw text to the runer pane. This command will not open a new pane if one
does not already exist. You will need to use VimuxOpenPane to do this. This
command can be used to interact with REPLs or other interactive terminal
programs that are not shells.


------------------------------------------------------------------------------
                                                               *VimuxSendKeys*
VimuxSendKeys~

Send keys to the runner pane. This command will not open a new pane if one
does not already exist. You will need to use VimuxOpenPane to do this. You can
use this command to send keys such as "Enter" or "C-c" to the runner pane.

------------------------------------------------------------------------------
                                                               *VimuxOpenPane*
VimuxOpenPane~

This will either open a new pane or use the nearest pane and set it as the
vimux runner pane for the other vimux commands. You can control if this command
uses the nearest pane or always creates a new one with g:VimuxUseNearestPane

------------------------------------------------------------------------------
                                                            *VimuxPromptCommand*
VimuxPromptCommand~

Prompt for a command and run it in a small horizontal split bellow the current
pane.
>
 " Prompt for a command to run map
 <Leader>vp :VimuxPromptCommand<CR>
<

------------------------------------------------------------------------------
                                                           *VimuxRunLastCommand*
VimuxRunLastCommand~

Run the last command executed by `VimuxRunCommand`
>
 " Run last command executed by VimuxRunCommand
 map <Leader>vl :VimuxRunLastCommand<CR>
<

------------------------------------------------------------------------------
                                                            *VimuxInspectRunner*
VimuxInspectRunner~

Move into the tmux runner pane created by `VimuxRunCommand` and enter copy
pmode (scroll mode).
>
 " Inspect runner pane map
 <Leader>vi :VimuxInspectRunner<CR>
<

------------------------------------------------------------------------------
                                                            *VimuxCloseRunner*
VimuxCloseRunner~

Close the tmux runner created by `VimuxRunCommand`
>
 " Close vim tmux runner opened by VimuxRunCommand
 map <Leader>vq :VimuxCloseRunner<CR>
<

------------------------------------------------------------------------------
                                                          *VimuxInterruptRunner*
VimuxInterruptRunner~

Interrupt any command that is running inside the
runner pane.
>
 " Interrupt any command running in the runner pane map
 <Leader>vs :VimuxInterruptRunner<CR>
<



------------------------------------------------------------------------------
                                                          *VimuxClearRunnerHistory*
VimuxClearRunnerHistory~

Clear ths tmux history of the runner pane for when
you enter tmux scroll mode inside the runner pane.
>
 " Clear the tmux history of the runner pane
 <Leader>vc :VimuxClearRunnerHistory<CR>
<


==============================================================================
MISC (3)                                                             *VimuxMisc*

------------------------------------------------------------------------------
                                                        *VimuxExampleKeybinding*
Full Keybind Example~

>
 " Run the current file with rspec
 map <Leader>rb :call VimuxRunCommand("clear; rspec " . bufname("%"))<CR>

 " Prompt for a command to run
 map <Leader>vp :VimuxPromptCommand<CR>
 
 " Run last command executed by VimuxRunCommand
 map <Leader>vl :VimuxRunLastCommand<CR>
 
 " Inspect runner pane
 map <Leader>vi :VimuxInspectRunner<CR>
 
 " Close vim tmux runner opened by VimuxRunCommand
 map <Leader>vq :VimuxCloseRunner<CR>
 
 " Interrupt any command running in the runner pane
 map <Leader>vx :VimuxInterruptRunner<CR>
>

------------------------------------------------------------------------------
                                                        *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.

>
 function! VimuxSlime()
  call VimuxSendText(@v)
  call VimuxSendKeys("Enter")
 endfunction

 " If text is selected, save it in the v buffer and send that buffer it to tmux
 vmap <LocalLeader>vs "vy :call VimuxSlime()<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 `VimuxRunCommand`
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.

  let g:VimuxHeight = "40"

Default: "20"

------------------------------------------------------------------------------
                                                *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
creating splits.

  let g:VimuxOrientation = "h"

Options:
  "v": vertical
  "h": horizontal

Default: "v"

------------------------------------------------------------------------------
                                           *VimuxConfiguration_use_nearest_pane*
2.3 g:VimuxUseNearestPane~

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

  let VimuxUseNearestPane = 1

Default: 0

------------------------------------------------------------------------------
                                             *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.

  let VimuxResetSequence = ""

Default: "q C-u"

------------------------------------------------------------------------------
                                                             *VimuxPromptString*
2.5 g:VimuxPromptString~

The string presented in the vim command line when Vimux is invoked. Be sure
to put a space at the end of the string to allow for distinction between
the prompt and your input.

  let g:VimuxPromptString = ""

Default: "Command? "

==============================================================================
vim:tw=78:ts=2:sw=2:expandtab:ft=help:norl: