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 .............................. |VimuxInterruptRunner|
      2.6 .............................. |VimuxClearTerminalScreen|
      2.7 .............................. |VimuxClearRunnerHistory|
      2.8 .............................. |VimuxZoomRunner|
      2.9 .............................. |VimuxRunCommandInDir|
    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|
  - |VimuxOpenRunner|
  - |VimuxRunLastCommand|
  - |VimuxCloseRunner|
  - |VimuxInspectRunner|
  - |VimuxInterruptRunner|
  - |VimuxPromptCommand|
  - |VimuxClearTerminalScreen|
  - |VimuxClearRunnerHistory|
  - |VimuxZoomRunner|
  - |VimuxRunCommandInDir|

------------------------------------------------------------------------------
                                                               *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 runner pane. This command will not open a new pane if one
does not already exist. You will need to use VimuxOpenRunner 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 VimuxOpenRunner to do this. You
can use this command to send keys such as "Enter" or "C-c" to the runner pane.

------------------------------------------------------------------------------
                                                               *VimuxOpenRunner*
VimuxOpenRunner~

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:VimuxUseNearest

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

Prompt for a command and run it in a small horizontal split bellow the current
pane. A parameter can be supplied to predefine a command or a part of the
command which can be edited in the prompt.
>
 " Prompt for a command to run map
 map <Leader>vp :VimuxPromptCommand<CR>
 map <Leader>vm :VimuxPromptCommand("make ")<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
 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
 map <Leader>vs :VimuxInterruptRunner<CR>
<


------------------------------------------------------------------------------
                                                          *VimuxClearTerminalScreen*
VimuxClearTerminalScreen~

Clear the terminal screen of the runner pane.
>
 " Clear the terminal screen of the runner pane.
 map <Leader>v<C-l> :VimuxClearTerminalScreen<CR>
<

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

Clear the 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
 map <Leader>vc :VimuxClearRunnerHistory<CR>
<

------------------------------------------------------------------------------
                                                          *VimuxZoomRunner*
VimuxZoomRunner~

Zoom the runner pane. Once its zoomed, you will need
to use tmux "<bind-key> z" to restore the runner pane.
Zoom requires tmux version >= 1.8
>

 " Zoom the tmux runner page
 map <Leader>vz :VimuxZoomRunner<CR>
<

------------------------------------------------------------------------------
                                                        *VimuxRunCommandInDir*
VimuxRunCommandInDir~

Runs the specified command inside the directory of
the currently opened file. Takes two arguments. command and inFile

command: The command to run
inFile: If 1 the filename will be appended to the command
>

 " Compile currently opened latex file to pdf
 autocmd Filetype tex nnoremap <buffer> <Leader>rr :update<Bar>:call VimuxRunCommandInDir('latexmk -pdf', 1)<CR>
 " Push the repository of the currently opened file
 nnoremap <leader>gp :call VimuxRunCommandInDir("git push", 0)<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>

 " Zoom the runner pane (use <bind-key> z to restore runner pane)
 map <Leader>vz :call VimuxZoomRunner()<CR>

 " Clear the terminal screen of the runner pane.
 map <Leader>v<C-l> :VimuxClearTerminalScreen<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 VimuxRunCommand(@v, 0)
 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*
2.3 g:VimuxUseNearest

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

  let g:VimuxUseNearest = 1

Default: 1

------------------------------------------------------------------------------
                                             *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 g: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? "

------------------------------------------------------------------------------
                                                             *VimuxRunnerType*
2.6 g:VimuxRunnerType~

The type of view object Vimux should use for the runner. For reference, a
tmux session is a group of windows, and a window is a layout of panes.

  let g:VimuxRunnerType = "window"

Options:
  "pane": for panes
  "window": for windows

Default: "pane"

------------------------------------------------------------------------------
                                                              *VimuxTmuxCommand*
2.7 g:VimuxTmuxCommand~

The command that Vimux runs when it calls out to tmux. It may be useful to
redefine this if you're using something like tmate.

  let g:VimuxTmuxCommand = "tmate"

Default: "tmux"

------------------------------------------------------------------------------
                                                              *VimuxOpenExtraArgs*
2.8 g:VimuxOpenExtraArgs~

Allows addtional arguments to be passed to the tmux command that opens the
runner. Make sure that the arguments specified are valid depending on whether
you're using panes or windows, and your version of tmux.

  let g:VimuxOpenExtraArgs = "-c #{pane_current_path}"

Default: "tmux"

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