vim-screen/vim-screen.txt

   1 *vim-screen.txt*        A plugin to start gnu screen within your vim session.
   2
   3 Plugin aims to simulate an embedded shell in vim by allowing you to easily
   4 convert your current vim session into one running in gnu screen with a split
   5 gnu screen window containing a shell, and to quickly send statements/code to
   6 whatever program is running in that shell (bash, python, irb, etc.).  Spawning
   7 the shell in your favorite terminal emulator is also supported for gvim users
   8 or anyone else that just prefers an external shell.
   9
  10 Commands:
  11
  12   :ScreenShell [cmd]
  13         Starts a screen hosted shell performing the following steps depending on
  14         your environment.
  15
  16         When running a console vim on a unix based OS (Linux, BSD, OSX):
  17         1. save a session file from your currently running vim instance
  18                 (current tab only)
  19         2. start gnu screen with vim running in it
  20         3. load your saved session file
  21         4. create a lower gnu screen split window and start a shell, or if
  22         g:ScreenShellExternal is set, start an external terminal with
  23         screen running.
  24         5. if a command was supplied to :ScreenShell, run it in the new shell.
  25                 Ex. :ScreenShell ipython
  26         Note: If you are already in a gnu screen session, then only steps 4 and
  27                 5 above will be run.
  28
  29         When running gvim:
  30         1. start an external terminal with screen running.
  31         2. if a command was supplied to :ScreenShell, run it in the new shell.
  32                 Ex. :ScreenShell ipython
  33
  34   :ScreenSend
  35         Send the visual selection or the entire buffer contents to the running gnu
  36         screen shell window.
  37
  38   :ScreenQuit
  39         Save all currently modified vim buffers and quit gnu screen, returning you
  40         to your previous vim instance running outside of gnu screen
  41
  42         Note: :ScreenQuit is not available if you where already in a gnu screen
  43                 session when you ran :ScreenShell.
  44     Note: By default, if the gnu screen session was started by :ScreenShell,
  45                 then exiting vim will quit the gnu screen session as well (configurable
  46                 via g:ScreenShellQuitOnVimExit).
  47
  48   :ScreenShellAttach [session]
  49         Sets the necessary internal variables to allow :ScreenSend invocations
  50         to send to the specified screen session.  If no session is provided,
  51         then the first session found is used.  If the session is in the "Detached"
  52         state, then a new terminal is opened with a new screen instance attached
  53         to the session. Attaching to a detached session is not currently supported
  54         on windows due to deficiencies in the cygwin version of gnu screen.
  55         Also note, that for screen sessions attached to via this
  56         mechanism, :ScreenSend invocations will send the text to the active screen
  57         window instead of targeting the 'shell' window when used from :ScreenShell.
  58
  59 An example workflow may be:
  60         Open a python file to work on:
  61                 $ vim something.py
  62
  63         Decide you want to run all or pieces of the code in an interactive
  64         python shell:
  65                 :ScreenShell python
  66
  67         Send code from a vim buffer to the shell:
  68                 :ScreenSend
  69
  70         Quit the screen session and return to your original vim session:
  71         :ScreenQuit
  72                 or
  73         :qa
  74
  75 Configuration:
  76
  77         g:ScreenShellHeight (Default: 15)
  78                 Sets the height of gnu screen region used for the shell.
  79
  80         g:ScreenShellQuitOnVimExit (Default: 1)
  81                 When non-zero and the gnu screen session was started by this script,
  82                 the screen session will be closed when vim exits.
  83
  84         g:ScreenShellExternal (Default: 0)
  85                 When non-zero and not already in a screen session, an external shell
  86                 will be spawned instead of using a split region for the shell.
  87                 Note: when using gvim, an external shell is always used.
  88
  89         g:ScreenShellServerName
  90                 If the gnu screen session is started by this plugin, then the value
  91                 of this setting will be used for the servername arg of the vim instance
  92                 started in the new gnu screen session (not applicable for gvim users).
  93                 The default is 'vim' unless you have g:ScreenShellExternal enabled, in
  94                 which case, if you still want to restart vim in a screen session with
  95                 a servername, then simply set this variable in your vimrc.
  96
  97         g:ScreenShellTerminal (Default: '')
  98                 When g:ScreenShellExternal is enabled or you are running gvim, this
  99                 value will be used as the name of the terminal executable to be used.
 100                 If this value is empty, a list of common terminals will be tried until
 101                 one is found.
 102
 103 Gotchas:
 104         While running vim in gnu screen, if you detach the session instead of
 105     quitting, then when returning to the non-screen vim, vim will complain
 106     about swap files already existing.  So try to avoid detaching.
 107
 108         Not all vim plugins support saving state to or loading from vim
 109     session files, so when running :ScreenShell some buffers may not load
 110     correctly if they are backed by such a plugin.