:: vimsh readme ::
vimsh is a python script and vim script that allow a user to run a shell within a [g]vim buffer. There are certain requirements and some limitations depending on your platform so please read on. vimsh works on both the console and GUI versions of vim so from this point on references to vim also include GUI versions of vim.
- NOTE
If you like this script and vim users are allowed to vote on new
features in vim again, PLEASE put in a vote for vi editing in the ex
command window ( not the new command window/buffer ). It's the only
new feature I would like vim to have.
:: vimsh requirements ::
requirements summary:
python enabled vim ( +python )
operating system that supports pty (unix) -or- popen/pipes (Windows)
python 2.2 or higher, may work with 2.0, but not tested.
Tested w/ 2.2 and 2.3.
requirements in detail:
vimsh requires a python enabled vim ( +python ), run :ver to see if you have +python for your build of vim.
vimsh also requires that your operating system supports either pty ( pseudo ttys ) -or- the popen family of calls. Most unix variants have support for pty in one form or another and most other platforms, for instance Windows, support popen.
I have tested vimsh on the following configurations, newer releases are not always tested with all platforms:
vim 6.0-6.2 / Slackware Linux 8.0 / python 2.2b2, 2.2.3, 2.3.X
vim 6.0-6.2 / Gentoo Linux / python 2.3.3
vim 6.0-6.2 / WinNT 4.0 / Activestate Python 2.2
vim 6.0-6.2 / Win2K / Standard Python 2.2
vim 6.0-6.2 / WinXP / Standard Python 2.2
vim 6.0-6.2 / FreeBSD 4.6-4.9 / python 2.2.X, 2.3.X
The pty library is 'unsupported' by python on some platforms but I have received reports of success on these platforms in addition to the ones I have tested on:
QNX
Solaris( waiting for confirmation of fix )
:: running vimsh ::
You can run vimsh by sourcing the file vimsh.vim on the ex command line like this assuming you are in the directory that vimsh.vim is located:
:source vimsh.vim
It is much easier to assign a key mapping to load it. <Leader> is what ever you use as your leader sequence, I personally use '\'.
A useful mapping might be:
nmap <Leader>sh :source <path_to_script>/vimsh.vim<CR>
I use one like this:
nmap \sh :source <path_to_script>/vimsh.vim<CR>
There is a python script, vimsh.py, that needs to be in the same directory as vimsh.vim. It should have been included in the .tar.gz or .zip file you downloaded as well as this file, a TODO file, and the ChangeLog.
Putting the scripts in your plugin directory is not recommended.
You can also run have multiple buffers using vimsh:
:VimShNewBuf foo
will create a new additional vimsh buffer with the name foo.
:: vimsh license ::
Use at your own risk. I'm not responsible if it hoses your machine. All I ask is that I'm made aware of changes so I can incorporate them into my version, that and my contact info stays in the script.
:: vimsh limitations ::
Running a shell within vim has it's limitations due to the fact that vim doesn't have the code necessary to run an interactive shell. vimsh uses different methods to allow this to happen using python.
general limitations:
Can only execute line oriented programs, no vim within vim stuff,
emacs, [n]curses, pagers, etc.
- pty
The best support and formatting. Most unix platforms support ptys.
You can run interactive line based commands like ftp, telnet, rm,
ping, cp, ssh, etc.
Only current limitation is involving commands that have
continuous output (ping) or slow commands (ftp). You will need
to use the refresh key (F5, remappable) to see output sometimes.
I've tried everything I can possibly think of to try and get it
to work but nothing has. See vimsh.vim for what's been tried,
I'm open to suggestions. If vim ever gets an idle processing
function, akin to CursorHold, but without the limitations, this
will work properly.
- popen
Only non-interactive programs are supported. Since this mostly applies
to the Windows platform, this means you can run programs like:
dir, findstr, type, attrib, set, ping, etc.
Interactive programs like ftp, telnet, ssh will not work
correctly.
This is because these programs seem to use buffered output or write
directly to the console using the Windows Console API. Unfortunately,
this means that without pty functionality for windows ( or a lot of
work on my part ), these commands cannot be run within vimsh.
Also commands that wait on standard input currently cannot
be interrupted w/ ctrl-c. i.e. running 'findstr foo', since
there is no file spec the command will wait and hang the shell
session within vim. Just delete the buffer if this happens (:bd).
:: vimsh customization ::
It is recommended not to modify the vimsh.py or vimsh.vim to customize vimsh. Support exists in vimsh to retreive settings that have been set in your .[g]vimrc or equivalent.
Here are some examples of how it would look in a .vimrc:
let g:vimsh_prompt_override = 1 # will not use normal prompt from your 'real' shell
let g:vimsh_prompt_pty = "%m%" ## specify overriden prompt
let g:vimsh_split_open = 0 ## run vimsh in the current buffer
let g:vimsh_sh = "/bin/zsh" ## shell to run within vimsh
The list of variables was getting too long and that meant I had to duplicate what was already in vimsh.py in this file, so please read vimsh.py for variables that can be customized. Look for the section in the file labeled 'customization'.
:: vimsh notes ::
The timeouts for reading are set low ( <= 0.2 sec ) for local filesystem and application use. If you plan on running telnet/ftp/ssh etc, pretty much any network based app, you can bump up the timeouts if you have a slower connection. This is not an exact science. If you're not seeing all of the output or having to hit enter to see output you can bump the timeout up. Being conservative won't hurt. See the mappings for setting the timeouts for reads and refreshing output. If you don't want to change the timeouts you can just press Enter or F5 to check for more output from the command.
:: vimsh tips ::
If you run tcsh or csh the following will allow you to have a better environment when using vimsh.
Add these to your .vimrc:
let g:vimsh_pty_prompt_override = 0
let g:vimsh_sh = '/bin/tcsh'
let $VIMSH = 1
The $VIMSH can then be detected in your .cshrc to do special processing. For instance, vimsh doesn't support ANSI escape sequences yet so I unalias ls with color:
if ($?VIMSH) then
unalias ls
endif
:: vimsh help ::
Feel free to email me (bsturk@adelphia.net) with issues regarding vimsh or if you've found a bug etc. Please read this file, the ChangeLog, and the TODO to see if I already know about the issue, or is a known limitation before contacting me. If you do email me please include the output of :ver from vim, the version of python you have installed, what operating system you are running, and the output of running vimsh w/ DEBUG set to 1 in vimsh.py in your email.
:: vimsh info ::
The latest version is always available @
http://users.adelphia.net/~bsturk/vim.html
Please send bug reports, suggestions, and other email to