fc3acbaded
These commands allow for arbitrary text in the Vim buffer to be passed to the runner pane for execution.
388 lines
17 KiB
Plaintext
388 lines
17 KiB
Plaintext
*vim-tmux-runner.txt* For Vim version 7.3 Last change: 2012 Nov 25
|
||
|
||
Vim Tmux Runner
|
||
Vim and tmux, sittin' in a tree...
|
||
|
||
==============================================================================
|
||
CONTENTS *vtr-contents*
|
||
|
||
1. About............................ |VTR-About|
|
||
2. Usage ........................... |VTR-Usage|
|
||
2.1 ............................... |VtrSendCommandToRunner|
|
||
2.2 ............................... |VtrSendLineToRunner|
|
||
2.3 ............................... |VtrSendSelectedToRunner|
|
||
2.4 ............................... |VtrOpenRunner|
|
||
2.5 ............................... |VtrKillRunner|
|
||
2.6 ............................... |VtrFocusRunner|
|
||
2.7 ............................... |VtrResizeRunner|
|
||
2.8 ............................... |VtrReorientRunner|
|
||
2.9 ............................... |VtrDetachRunner|
|
||
2.10 ............................... |VtrReattachRunner|
|
||
2.11 ............................... |VtrClearRunner|
|
||
2.12 ............................... |VtrFlushCommand|
|
||
3. Configuration ................... |VTR-Configuration|
|
||
3.1 ................................ |VtrPercentage|
|
||
3.2 ................................ |VtrOrientation|
|
||
3.3 ................................ |VtrInitialCommand|
|
||
3.4 ................................ |VtrGitCdUpOnOpen|
|
||
3.5 ................................ |VtrClearBeforeSend|
|
||
3.5 ................................ |VtrPrompt|
|
||
3.6 ................................ |VtrUseVtrMaps|
|
||
3.7 ................................ |VtrClearOnResize|
|
||
3.8 ................................ |VtrClearOnReorient|
|
||
3.9 ................................ |VtrClearOnReattach|
|
||
3.10 ............................... |VtrDetachedName|
|
||
3.11 ............................... |VtrClearSequence|
|
||
3.12 ............................... |VtrInitTimeout|
|
||
|
||
==============================================================================
|
||
ABOUT (1) *VTR-About*
|
||
|
||
VTR -- Straightforward vim/tmux integration
|
||
|
||
This plugin provides vim with an understanding of tmux. The plugin provides
|
||
functionality to open a small tmux pane and send commands to run in that tmux
|
||
pane.
|
||
|
||
This plugin was created by Chris Toomey[1]. Any bugs or feature requests can
|
||
be entered at the github repo[2] for the plugin. Any feedback is greatly
|
||
appreciated.
|
||
|
||
This plugin was heavily inspired by Vimux[3]. It is meant to provide a very
|
||
similar feature set to Vimux, but use native vimscript. In addition VTR
|
||
provides a few commands beyond those in Vimux, such as the ability to rotate
|
||
the runner pane between orientations.
|
||
|
||
[1] http://ctoomey.com
|
||
[2] https://github.com/christoomey/vim-tmux-runner/issues
|
||
[3] https://github.com/benmills/vimux
|
||
|
||
==============================================================================
|
||
USAGE (2) *VTR-Usage*
|
||
|
||
VTR provides a collection of commands and functions that allow vim to interact
|
||
with tmux. The primary function is VTRSendCommand. This allows for any command
|
||
string to be passed to tmux for execution.
|
||
|
||
VTR uses a tmux "pane" to execute the provided command. A tmux pane is very
|
||
similar to a vim split. Throughout VTR, this tmux pane used for command
|
||
execution is referred to as the "runner". The runner by default will contain
|
||
an instance of the default system shell, but other executables such as a
|
||
python REPL, ruby irb session, or similar can be used. The power of VTR, and
|
||
tmux, is that each pane is a fully independant shell environment. None the
|
||
less, tmux allows for communication between these environments and it is this
|
||
ability that give VTR its power.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrSendCommandToRunner*
|
||
2.1 VtrSendCommandToRunner~
|
||
|
||
Send a command to the tmux runner pane. This is the primary purpose of VTR. A
|
||
new runner pane will be created. A detached pane will be reattached. By
|
||
default, the runner will be cleared before sending the provided command, but
|
||
this behavior can be disabled with the |VtrClearBeforeSend| setting.
|
||
|
||
The first time this command is called, it will prompt for a command to send to
|
||
the runner. The specific prompt text can be configured via the |VtPrompt|
|
||
setting. The command is then stored in an internal variable and will
|
||
continue to be used for subsequent calls to the command. The stored command
|
||
can be cleared using |VtrFlushCommand|.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrSendLineToRunner*
|
||
2.2 VtrSendLineToRunner~
|
||
|
||
Send the current line to the runner pane for execution.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrSendSelectedToRunner*
|
||
2.3 VtrSendSelectedToRunner~
|
||
|
||
Send the current visual selection to the runner pane for execution.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrOpenRunner*
|
||
2.4 VtrOpenRunner~
|
||
|
||
Open a tmux pane, referred to as the "runner", adjacent to the tmux pane
|
||
containing the current vim session. This command will make use of the
|
||
|VtrOrientation| and |VtrPercentage| settings. Note, this command will
|
||
restore a detached pane or create a new one as needed.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrKillRunner*
|
||
2.5 VtrKillRunner~
|
||
|
||
Kill the tmux runner pane. this pane will kill either the local or detached
|
||
runner pane. this command does nothing if there is currently not a runner
|
||
pane.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrFocusRunner*
|
||
2.6 VtrFocusRunner~
|
||
|
||
Move the cursor to the runner to interact directly with it. A new runner will
|
||
be created if one does not exist and a detached pane will be restored as
|
||
needed.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrResizeRunner*
|
||
2.7 VtrResizeRunner~
|
||
|
||
Prompt for a new percentage then resize the runner pane to that percentage.
|
||
This command will update the |VtrPercentage| setting for the current vim
|
||
session. The |VtrPercentage| will be reset if vim is closed. By default, the
|
||
runner will be cleared after resizing, but this behavior can be disabled
|
||
with the |VtrClearOnResize| setting.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrReorientRunner*
|
||
2.8 VtrReorientRunner~
|
||
|
||
Switch the runner pane from its current orientation to the alternate
|
||
orientation (horizontal or vertical). The |VtrPercentage| will be maintained
|
||
through the reorientation. By default, the runner will be cleared after
|
||
reorienting, but this behavior can be disabled with the |VtrClearOnReorient|
|
||
setting.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrDetachRunner*
|
||
2.9 VtrDetachRunner~
|
||
|
||
Detach the runner pane to its own window while keeping the cursor focus on the
|
||
vim window. This command is useful if there are details in the runner pane or
|
||
significant setup implemented in the runner pane that will be useful at a
|
||
later time, but current the runner pane is not needed. Rather than killing the
|
||
runner, this command simply stashes it away in its own window until it is
|
||
needed again. The runner can later be restored with any of |VtrReattachRunner|,
|
||
|VtrOpenRunner|, or |VtrFocusRunner|. The runner can still be killed with the
|
||
|VtrKillRunner| command.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrReattachRunner*
|
||
2.10 VtrReattachRunner~
|
||
|
||
Reattach the runner pane. This command assumes that the runner has previously
|
||
been dismissed using the |VtrDetachRunner| command. The pane will be restored
|
||
with the last |VtrOrientation| and |VtrPercentage| combination used. By
|
||
default the runner pane will be cleared after being reattached, but this
|
||
behavior can be disabled using the |VtrClearOnReattach| setting.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrClearRunner*
|
||
2.11 VtrClearRunner~
|
||
|
||
Send the key sequence defined by the |VtrClearSequence| setting to the runner.
|
||
By default this will clear any unfinished commands at the shell prompt and
|
||
move the prompt up to hide any previous command output.
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrFlushCommand*
|
||
2.12 VtrFlushCommand~
|
||
|
||
Flush the previous run command variable. After running this command, the next
|
||
run of |VtrSendCommandToRunner| will again prompt for the command to run.
|
||
|
||
==============================================================================
|
||
CONFIGURATION (3) *VTR-Configuration*
|
||
|
||
You can configure VTR using the following settings:
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrPercentage*
|
||
3.1 g:VtrPercentage~
|
||
|
||
The percent of the tmux window the runner pane will occupy.
|
||
|
||
let g:VtrPercentage = 35
|
||
|
||
Default: 20
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrOrientation*
|
||
3.2 g:VtrOrientation~
|
||
|
||
The orientation used when creating the tmux split pane to use as the runner
|
||
pane. The orientation argument is the inverse of vim's, ie "horizontal" splits
|
||
in tmux will create a new pane to the right of the existing pane.
|
||
|
||
let g:VtrOrientation = "h"
|
||
|
||
Options:
|
||
"v": vertical (split pane below vim pane)
|
||
"h": horizontal (split pane to the right of vim pane)
|
||
|
||
Default: "v"
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrInitialCommand*
|
||
3.3 g:VtrInitialCommand~
|
||
|
||
Provide a command to be run just after the runner pane is created. This can
|
||
be used to set the working directory, define an environment variable, etc.
|
||
No command will be run if this is set to an empty string.
|
||
|
||
let g:VtrInitialCommand = "cd .."
|
||
|
||
Default: ""
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrInitialCommand*
|
||
3.4 g:VtrGitCdUpOnOpen~
|
||
|
||
When opening a new runner, if currently within a git repo then change the
|
||
working directory to the root of the git repo. This can be useful for some
|
||
test runners which behave differently depending on where they are run from. By
|
||
default this functionality is disabled.
|
||
|
||
let g:VtrInitialCommand = 1
|
||
|
||
Default: 0
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrClearBeforeSend*
|
||
3.5 g:VtrClearBeforeSend~
|
||
|
||
Before sending a command to the runner pane, send the clear sequence defined
|
||
by the |VtrClearSequence| setting. This will make it easier to view and
|
||
interpret the output in the runner pane. Set this to 0 to disable.
|
||
|
||
let g:VtrClearBeforeSend = 0
|
||
|
||
Default: 1
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrPrompt*
|
||
3.5 g:VtrPrompt~
|
||
|
||
The string used when prompting for a command to run. It is best to include a
|
||
space at the end of this string to visually separate the prompt from the users
|
||
command.
|
||
|
||
let g:VtrPrompt = "What can I do you for?: "
|
||
|
||
Default: "Command to run: "
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrUseVtrMaps*
|
||
3.6 g:VtrUseVtrMaps~
|
||
|
||
Allow VTR to define a set of key mappings to provide easy access to the VTR
|
||
command set. As a vim user, I consider my <leader> space to be sacred, so
|
||
these maps are disabled by default. To allow VTR to set its maps, add the
|
||
following to your vimrc:
|
||
|
||
let g:VtrUseVtrMaps = 1
|
||
|
||
The following normal mode maps are provided when g:VtrUseVtrMaps is set to 1:
|
||
|
||
Mapping | Command
|
||
-----------------------------
|
||
<leader>rr | VtrResizeRunner<cr>
|
||
<leader>ror | VtrReorientRunner<cr>
|
||
<leader>sc | VtrSendCommandToRunner<cr>
|
||
<leader>sl | VtrSendLineToRunner<cr>
|
||
<leader>or | VtrOpenRunner<cr>
|
||
<leader>kr | VtrKillRunner<cr>
|
||
<leader>fr | VtrFocusRunner<cr>
|
||
<leader>dr | VtrDetachRunner<cr>
|
||
<leader>ar | VtrReattachRunner<cr>
|
||
<leader>cr | VtrClearRunner<cr>
|
||
<leader>fc | VtrFlushCommand<cr>
|
||
|
||
In addition, a single visual mode map is provided to send a visually selected
|
||
region to the runner pane:
|
||
|
||
Mapping | Command
|
||
-----------------------------
|
||
<leader>sv | VtrSendSelectedToRunner<cr>
|
||
|
||
Default: 0
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrClearOnResize*
|
||
3.7 g:VtrClearOnResize~
|
||
|
||
Send the |VtrClearSequence| after resizing the runner via the
|
||
|VtrResizeRunner| command. This option is turned off by default as
|
||
most often a resize is used to better see the content currently in
|
||
the runner pane.
|
||
|
||
let g:VtrClearOnResize = 1
|
||
|
||
Default: 0
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrClearOnReorient*
|
||
3.8 g:VtrClearOnReorient~
|
||
|
||
Send the |VtrClearSequence| after reorienting the runner via the
|
||
|VtrReorientRunner| command.
|
||
|
||
let g:VtrClearOnReorient = 0
|
||
|
||
Default: 1
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrClearOnReattach*
|
||
3.9 g:VtrClearOnReattach~
|
||
|
||
Send the |VtrClearSequence| after reattaching the runner via the
|
||
|VtrReattachRunner| command.
|
||
|
||
let g:VtrClearOnReattach = 0
|
||
|
||
Default: 1
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrDetachedName*
|
||
3.10 g:VtrDetachedName~
|
||
|
||
The name to use for the temporary window used when dismissing the runner via
|
||
the |VtrDetachRunner| command. This is provided in the rare event that the
|
||
window name "VTR_Pane" is already used and you would like to distinguish the
|
||
VTR detached runner pane window.
|
||
|
||
let g:VtrDetachedName = "WildAndWackyWindowName"
|
||
|
||
Default: "VTR_Pane"
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrClearSequence*
|
||
3.11 g:VtrClearSequence~
|
||
|
||
The character sequence to send to clear the runner. This sequence is used in
|
||
the explicit VTR comamnd |VtrClearRunner|. In addition, the sequence may be
|
||
used with the commands |VtrSendCommandToRunner|, |VtrResizeRunner|,
|
||
|VtrReattachRunner|, and |VtrReorientRunner| depending on the current value of
|
||
their respective "ClearOn" settings.
|
||
|
||
The default sequence will clear any unfinished commands sent to the shell
|
||
prompt within the runner pane and clear the scrollback history to present a
|
||
clean prompt ready for the next command. The character literals, , for
|
||
<Ctrl-u> and <Ctrl-l> respectively, can be inserted using <Ctrl-v> while in
|
||
insert mode. See the help file, ':help i_Ctrl-v', for more detail.
|
||
|
||
let g:VtrClearSequence = " "
|
||
|
||
Default: " "
|
||
|
||
------------------------------------------------------------------------------
|
||
*VtrInitTimeout*
|
||
3.12 g:VtrInitTimeout~
|
||
|
||
Timeout in milliseconds to use when initializing the runner in temporary
|
||
window. This is intended to provide the runner sufficient time to run the
|
||
initializing commands and then be attached to the Vim window.
|
||
|
||
This timeout is only relevant if VTR is configured to cd to the git root, or
|
||
run an initial command. These can be set through their respective
|
||
configuration options, |g:VtrGitCdUpOnOpen| and |g:VtrInitialCommand|.
|
||
|
||
let g:VtrInitTimeout = 100
|
||
|
||
Default: 500
|
||
|
||
==============================================================================
|
||
vim:tw=78:ts=2:sw=2:expandtab:ft=help:norl:
|