*vimshell.txt* Powerful shell implemented by Vim script Version: 11.1 Author : Shougo License: MIT license {{{ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. }}} CONTENTS *vimshell-contents* Introduction |vimshell-introduction| Install |vimshell-install| Interface |vimshell-interface| Commands |vimshell-commands| Variables |vimshell-variables| Functions |vimshell-functions| Key mappings |vimshell-key-mappings| Vimshell buffer key mappings |vimshell-buffer-key-mappings| Interactive buffer key mappings |vimshell-interactive-buffer-key-mappings| Options |vimshell-options| Examples |vimshell-examples| Internal Commands |vimshell-internal-commands| Special Commands |vimshell-special-commands| Alter Command |vimshell-alter-command| Hook |vimshell-hook| Tips |vimshell-tips| Unite sources |vimshell-unite-sources| Create plugin |vimshell-create-plugin| FAQ |vimshell-faq| ============================================================================== INTRODUCTION *vimshell-introduction* *vimshell* is an extreme shell that doesn't depend on external shells but is written completely in pure Vim script. To be honest the implementation is not as mature as eshell yet. The most important characteristic of vimshell is that it can collaborate with other Vim plugins. Additionally, for example, vimshell also works on Windows where there are no good shells at all; note that you cannot use full set of vimshell features on Windows though. Furthermore, vimshell borrowed handy functionalities from other shells. Vimshell has built-in functionalities that you had to set up to enable if it's on zsh. Vimshell doesn't pursue being completely compatible with average shells but aims to be a handy shell, so some behaviours like the rule of variables are a little bit different to them. ============================================================================== USAGE *vimshell-usage* You can start vimshell in ":VimShell", or use helpful keymap already defined. Because vimshell works similar with a common shell, you may operate it intuitively. But vimshell performs the path appointment in '/'. Vimshell fails to recognize escape sequences when you use '\' on Windows for a path and does not work. vimshell reads .vimshrc as initialize file. It might be helpful to add alias configurations. Note: vimshell has nothing to do with bash or zsh, so as to have no compatibilities. vimshell doesn't read .bashrc or .zshrc, but environment variables by "vimshell-internal-source". ============================================================================== INSTALL *vimshell-install* vimshell depends on |vimproc| http://github.com/Shougo/vimproc You must install and compile vimproc Ver.5.0 (or later) before using vimshell (refer to |vimproc-install|). ============================================================================== INTERFACE *vimshell-interface* ------------------------------------------------------------------------------ COMMANDS *vimshell-commands* :VimShell [{options}...] [{path}] *:VimShell* Runs vimshell. The {path} will be its current directory. If you omit {path}, it uses Vim's current directory (or does not change the current directory). If another vimshell buffer exists in the current tab, switches to the vimshell buffer and changes its current directory to {path}. Note: This feature is if installed unite.vim only. {options} are options for a vimshell buffer. See |vimshell-options|. :VimShellCreate [{options}...] [{path}] *:VimShellCreate* Runs vimshell as the same :VimShell, but it creates a new vimshell buffer instead of activating other vimshells which are up and running. :VimShellTab [{options}...] [{path}] *:VimShellTab* It's same as |:VimShellCreate|, but creates a new tab. :VimShellPop [{options}...] [{path}] *:VimShellPop* Like as |:VimShell|, but this command popups little window. It will be your help when you want to make vimshell a bit help. To split it, |g:vimshell_popup_command| is suited command. Note: It sets |vimshell-options-toggle|. You can toggle vimshell buffer. :VimShellCurrentDir [{options}...] [{path}] *:VimShellCurrentDir* Like as |:VimShell|, but move to the current directory. :VimShellBufferDir [{options}...] [{path}] *:VimShellBufferDir* Like as |:VimShell|, but move to buffer's directory. :VimShellExecute [{option}] [{command}] *:VimShellExecute* It does not run vimshell, but launches a terminal program you Specify by {command}, and this program runs in background. You can use vimshell like as GNU screen. {option} is same to |vimshell-internal-bg| options. If omit {command}, current buffer path is used. :VimShellInteractive [{option}] [{command}] *:VimShellInteractive* It does not run vimshell, but launches an interpreter program you specify by {command}. It is same as Emacs's M-x {interpreter-name}. You leave out {command}, vimshell uses the value in |g:vimshell_interactive_interpreter_commands|. {option} is same to |vimshell-internal-iexe| options. Resize window example: > VimShellInteractive --split='split | resize 20' irb < :VimShellTerminal [{option}] {command} *:VimShellTerminal* It does not run vimshell, but same as Emacs's ansi-term, it launches a terminal program you Specify by {command}. {option} is same to |vimshell-internal-texe| options. Note: This is not a completed function. :[range]VimShellSendString {string} *:VimShellSendString* It sends selected string to the interpreter in background buffer of vimshell, iexe, texe. You can control interpreter as if you are using |quickrun|. Cf: |vimshell#interactive#send()| Note: If interpreter is not loaded in the current tab, you can run interpreter command. :VimShellSendBuffer {bufname} *:VimShellSendBuffer* Sets background buffer as {bufname}. When {bufname} isn't showed, it will be opened automatically. ------------------------------------------------------------------------------ VARIABLES *vimshell-variables* g:vimshell_prompt *g:vimshell_prompt* Sets vimshell default prompt string. Initial value is "vimshell%". Note: This is a fixed string. You cannot change it dynamically (for example: current directory). (cf: |g:vimshell_user_prompt|) g:vimshell_prompt_expr *g:vimshell_prompt_expr* Sets vimshell default prompt expression. Initial value is "". This value is evaluated when vimshell redraws prompt. Note: You cannot get multi-line prompt. Note: If you set it, you must set prompt_pattern. Note: You cannot change prompt color dynamically. > " Use current directory as vimshell prompt. let g:vimshell_prompt_expr = \ 'escape(fnamemodify(getcwd(), ":~").">", "\\[]()?! ")." "' let g:vimshell_prompt_pattern = '^\%(\f\|\\.\)\+> ' < g:vimshell_prompt_pattern *g:vimshell_prompt_pattern* Sets the pattern which matches vimshell prompt. Initial value is "". If it is not set, vimshell will set the pattern automatically. g:vimshell_secondary_prompt *g:vimshell_secondary_prompt* Sets vimshell default secondary prompt string. Initial value is "%%". Note: This is fixed string. You cannot change it dynamically (for example: current directory). (cf: |g:vimshell_user_prompt|) g:vimshell_user_prompt *g:vimshell_user_prompt* You can define additional prompt to substitute a string for this. Note: Unlike |g:vimshell_prompt|, it can be a non-fixed string. You can get multi-line prompt by separating "user prompt" with "\n". This example will be helpful to show the current directory every time. > let g:vimshell_user_prompt = 'fnamemodify(getcwd(), ":~")' < g:vimshell_right_prompt *g:vimshell_right_prompt* It's zsh-like right prompt. This value is a string value which is an expression of Vim script. Similar to |g:vimshell_user_prompt|, but this calculates the window size, and shows the prompt on preferable position. Initial value is an empty string. *g:vimshell_force_overwrite_statusline* g:vimshell_force_overwrite_statusline If this variable is 1, vimshell will overwrite 'statusline' automatically. Note: If you want to change 'statusline' in vimshell buffer, you must set it to 0. The default value is 0. *g:vimshell_no_default_keymappings* g:vimshell_no_default_keymappings Disables all default key mappings in vimshell. You cannot use vimshell functions unless you set new key mappings, so it is for hackers who have understood the inner behaviors, and not recommended for newbies. *g:vimshell_use_terminal_command* g:vimshell_use_terminal_command When executes |vimshell-internal-shell|, this option set terminal program execute shell. "ckw -e" in Windows, "gnome-terminal -e" in Linux, become a candidate of value. Initial value is an empty string. g:vimshell_data_directory *g:vimshell_data_directory* Specify directories to store vimshell configurations. And history file is saved in this directory. Default value is "$XDG_CACHE_DIR/vimshell" or expand("~/.cache/vimshell"); the absolute path of it. g:vimshell_temporary_directory *g:vimshell_temporary_directory* Note: It is deprecated name. g:vimshell_max_command_history *g:vimshell_max_command_history* Maximum number of entries in history. If it is < 0, you can use infinite histories. Initial value is 1000. g:vimshell_max_directory_stack *g:vimshell_max_directory_stack* Maximum number of directory stacks saved by vimshell. Initial value is 100. g:vimshell_vimshrc_path *g:vimshell_vimshrc_path* Sets a setting file read by vimshell first. This is similar to .bashrc in bash. It is convenient when you define aliases. Initial Value is "expand('~/.vimshrc')". g:vimshell_escape_colors *g:vimshell_escape_colors* A list of colors correspond to coloring in escape sequence. 0-8 as normal colors, 9-15 as highlight colors. Initial value is written in plugin/vimshell.vim. *g:vimshell_disable_escape_highlight* g:vimshell_disable_escape_highlight This value controls whether vimshell highlights escape sequences. Disabling this function make vimshell faster because processing this is hard task. Note: This value is negative logic, so True means disabling. Default value is 0. g:vimshell_cat_command *g:vimshell_cat_command* Sets $PAGER command path. Note: This variable is useful for using pager commands. For example, "git log". Note: You *must not* set "core.pager" variable in your .gitconfig. Initial value is "cat". g:vimshell_editor_command *g:vimshell_editor_command* Sets $EDITOR command path. Note: This variable is useful for using editor commands. For example, "git commit" or "git rebase -i" commands. Note: This feature required GUI Vim and supported |+clientserver| feature. Note: To reflect external editor changes, you must write opened temporary buffer and execute |:bdelete| in external editor. Note: You *must not* set "core.editor" variable in your .gitconfig. Initial value "v:progname --servername=v:servername --remote-tab-wait-silent" or same to |g:vimshell_cat_command|. g:vimshell_environment_term *g:vimshell_environment_term* This value is $TERM on vimshell. Default value is "xterm". g:vimshell_split_command *g:vimshell_split_command* Vimshell uses this as the Ex command to split window. If you set this "nicely", vimshell adjusts with the current window size and splits window preferable ("nicely" depends on the winwidth variable). Empty means disabling window splitting on vimshell. "tabnew" means vimshell opens new tab. "vsplit" means vertical splitting. Default value is "nicely". g:vimshell_popup_command *g:vimshell_popup_command* Vimshell uses this as the Ex command to split window in |:VimShellPop|. If you leave this empty, vimshell uses "split" and |g:vimshell_popup_height|. Default value is "". g:vimshell_popup_height *g:vimshell_popup_height* This value is split height of |:VimShellPop|. This value is ratio percent against |winheight(0)|. Note: It is not used on non vimshell buffers (for example: interactive buffer). Default value 30. g:vimshell_cd_command *g:vimshell_cd_command* This is the Ex command to change the current directory. Default value is "lcd". *g:vimshell_no_save_history_commands* g:vimshell_no_save_history_commands This is a dictionary value that has keys of the command name that vimshell doesn't save in history. Default value is {'history' : 1, 'h' : 1, 'histdel' : 1, 'cd' : 1,}. g:vimshell_scrollback_limit *g:vimshell_scrollback_limit* This value is the maximum size of command output. Output buffer will be trim down if output is more than this value. Default value is 1000. *g:vimshell_enable_transient_user_prompt* g:vimshell_enable_transient_user_prompt If it is non-zero, vimshell will delete user prompt and right prompt line after executing |(vimshell_enter)| . Default value is 0. *g:vimshell_enable_start_insert* g:vimshell_enable_start_insert If it is non-zero, vimshell will start in insert mode. Default value is 1. *g:vimshell_enable_stay_insert* g:vimshell_enable_stay_insert If it is non-zero, vimshell will stay in insert mode after the command executed. Default value is 1. *g:vimshell_execute_file_list* g:vimshell_execute_file_list This is a dictionary value that has keys of the extensions and values of command arguments. This is used to define default file execution command. Default value is {}. *g:vimshell_interactive_no_save_history_commands* g:vimshell_interactive_no_save_history_commands This is a dictionary value which key is a command name that won't be save on the history in |vimshell-internal-iexe|. If there does not exist, it will be ignored. Default value is {}. *g:vimshell_interactive_update_time* g:vimshell_interactive_update_time When |vimshell-internal-iexe| is in Insert mode, this value controls the timing of auto update. |vimshell-internal-iexe| changes 'updatetime' based on this value. If it is 0, this feature is disabled. Default value is 200. *g:vimshell_interactive_command_options* g:vimshell_interactive_command_options This is a dictionary variable with command name key. The command |vimshell-internal-iexe| runs take this as its option. This option is used in such situation that you want to use a command that take some particular options or doesn't work well interactively, like in windows environments. Default value is too complicated, so please refer autoload/vimshell/commands/iexe.vim. *g:vimshell_interactive_interpreter_commands* g:vimshell_interactive_interpreter_commands This is a dictionary variable with filetype key and it is assignments of an interpreter name without arguments of |:VimShellInteractive|. Default value is too complicated, so please refer autoload/vimshell/commands/iexe.vim. *g:vimshell_interactive_encodings* g:vimshell_interactive_encodings This is a dictionary variable with command name key and it is assignments of an encoding for the command which vimshell runs. If the key contains "/", vimshell will check if command path matches it. Default value is complicated, so please refer autoload/vimshell/plugin/vimshell.vim. *g:vimshell_interactive_echoback_commands* g:vimshell_interactive_echoback_commands This is a dictionary variable with interpreter name key, and if the value is 1, iexe doesn't echoback when |vimshell-internal-iexe| is running, and otherwise does. This value has effect only on windows. Default value is complicated, so please refer plugin/vimshell.vim g:vimshell_terminal_cursor *g:vimshell_terminal_cursor* It is an assignment of cursor shape |vimshell-internal-texe| uses. 'guicursor' is temporary changed, so this value has effect only on gvim environments. Default value is 'i:block-Cursor/lCursor'. g:vimshell_terminal_commands *g:vimshell_terminal_commands* This is a dictionary variable with command name key, and when you run a command of which value is True, automatically |vimshell-internal-texe| is used. iexe doesn't echoback when |vimshell-internal-iexe| is running, and otherwise does. Default value is complicated, so please refer autoload/vimshell/commands/iexe.vim. *g:vimshell_interactive_cygwin_commands* g:vimshell_interactive_cygwin_commands This is a dictionary variable with command name key, and the value is an assignment of commands which runs via fakecygpty. It is used when you launch some application that works only on Cygwin (like ssh) by |vimshell-internal-iexe|. To know about fakecygpty, you should refer |vimshell-tips-fakecygpty|. Default value is complicated, so please refer autoload/vimshell/commands/iexe.vim. *g:vimshell_interactive_cygwin_path* g:vimshell_interactive_cygwin_path It is assigned to the pass vimshell refers when launching programs via fakecygpty. If the first argument of |vimshell-internal-iexe| is fakecygpty, vimshell searches command from |g:vimshell_interactive_cygwin_path| instead of $PATH. Default value is 'c:/cygwin/bin'. *g:vimshell_interactive_cygwin_home* g:vimshell_interactive_cygwin_home It is assigned to $HOME of the program launched via fakecygpty. Leavin '' means to use current $HOME. Default value is ''. *g:vimshell_interactive_monochrome_commands* g:vimshell_interactive_monochrome_commands This is a dictionary variable with command name key, and the value is an assignment of commands which you want to disable highlighting. Default value is complicated, so please refer autoload/vimshell/commands/iexe.vim. *g:unite_source_vimshell_external_history_path* g:unite_source_vimshell_external_history_path It is assignment of a history file that |vimshell/external_history| source recognizes. Default value is set to suit for 'shell' value. ------------------------------------------------------------------------------ KEY MAPPINGS *vimshell-key-mappings* (vimshell_split_switch) *(vimshell_split_switch)* Split screen and switches vimshell buffer. (vimshell_split_create) *(vimshell_split_create)* Split screen and creates vimshell buffer. (vimshell_switch) *(vimshell_switch)* Switches to vimshell buffer. (vimshell_create) *(vimshell_create)* Create vimshell buffer. VIMSHELL BUFFER KEY MAPPINGS *vimshell-buffer-key-mappings* Normal mode key mappings. (vimshell_enter) *(vimshell_enter)* Execute command line. *(vimshell_previous_prompt)* (vimshell_previous_prompt) Move to previous prompt from cursor. (vimshell_next_prompt) *(vimshell_next_prompt)* Move to next prompt from cursor. *(vimshell_delete_previous_output)* (vimshell_delete_previous_output) Delete previous output form cursor. (vimshell_paste_prompt) *(vimshell_paste_prompt)* Paste cursor line to last prompt. *(vimshell_move_end_argument)* (vimshell_move_end_argument) Move to command end argument. (vimshell_hide) *(vimshell_hide)* Hide vimshell buffer. (vimshell_exit) *(vimshell_exit)* Quit vimshell buffer. (vimshell_change_line) *(vimshell_change_line)* Change whole line. (vimshell_delete_line) *(vimshell_delete_line)* Delete whole line. (vimshell_hangup) *(vimshell_hangup)* Terminate command. (vimshell_interrupt) *(vimshell_interrupt)* Send interrupt. (vimshell_insert_head) *(vimshell_insert_head)* *(vimshell_insert_enter)* (vimshell_insert_enter) *(vimshell_append_enter)* (vimshell_append_enter) (vimshell_append_end) *(vimshell_append_end)* Enter insert mode. Note: If your cursor is on previous prompt, vimshell will copy the prompt automatically. (vimshell_clear) *(vimshell_clear)* Redraw vimshell buffer. (vimshell_move_head) *(vimshell_move_head)* Move to head. *(vimshell_execute_by_background)* (vimshell_execute_by_background) Execute command by iexe. Visual mode key mappings. *i_(vimshell_command_complete)* (vimshell_command_complete) Start completion. (vimshell_zsh_complete) *i_(vimshell_zsh_complete)* Start completion using zsh. Note: Required zsh and unite plugin. https://github.com/Shougo/unite.vim Note: It does not work in Windows! *i_(vimshell_push_current_line)* (vimshell_push_current_line) Push current line command to command line stack. *i_(vimshell_insert_last_word)* (vimshell_insert_last_word) Insert command last word. (vimshell_move_head) *i_(vimshell_move_head)* Move to line head. *i_(vimshell_delete_backward_line)* (vimshell_delete_backward_line) Delete backward line from cursor. *i_(vimshell_delete_backward_word)* (vimshell_delete_backward_word) Delete backward word from cursor. (vimshell_enter) *i_(vimshell_enter)* Execute command. (vimshell_interrupt) *i_(vimshell_interrupt)* Send interrupt. *i_(vimshell_move_previous_window)* (vimshell_move_previous_window) Move to previous window. *i_(vimshell_delete_backward_char)* (vimshell_delete_backward_char) *i_(vimshell_another_delete_backward_char)* (vimshell_another_delete_backward_char) Delete backward char from cursor. *i_(vimshell_delete_forward_line)* (vimshell_delete_forward_line) Delete forward line from cursor. (vimshell_clear) *i_(vimshell_clear)* Redraw vimshell buffer. *i_(vimshell_execute_by_background)* (vimshell_execute_by_background) Execute command by iexe. (vimshell_hide) *i_(vimshell_hide)* Hide vimshell buffer. (vimshell_exit) *i_(vimshell_exit)* Quit vimshell buffer. (vimshell_history_unite) *i_(vimshell_history_unite)* Execute vimshell history by unite interface. Note: To use it, you must install |unite.vim| plugin. *i_(vimshell_history_neocomplete)* (vimshell_history_neocomplete) Execute vimshell history by neocomplete interface. Note: To use it, you must install |neocomplete| plugin. *vimshell_default_key_mappings* Normal mode default key mappings. {lhs} {rhs} -------- ----------------------------- (vimshell_enter) q (vimshell_hide) Q (vimshell_exit) (vimshell_previous_prompt) (vimshell_next_prompt) (vimshell_paste_prompt) E (vimshell_move_end_argument) cc (vimshell_change_line) dd (vimshell_delete_line) I (vimshell_insert_head) A (vimshell_append_end) i (vimshell_insert_enter) a (vimshell_append_enter) ^ (vimshell_move_head) (vimshell_interrupt) (vimshell_hangup) (vimshell_clear) (vimshell_execute_by_background) *v_vimshell_default_key_mappings* Visual mode default key mappings. {lhs} {rhs} -------- ----------------------------- *i_vimshell_default_key_mappings* Insert mode default key mappings. {lhs} {rhs} -------- ----------------------------- (vimshell_enter) (vimshell_history_unite) / (vimshell_history_neocomplete) / (vimshell_history_neocomplete) (vimshell_command_complete) (vimshell_move_head) (vimshell_delete_backward_line) (vimshell_delete_backward_word) (while execute) (vimshell_execute_by_background) (other) (vimshell_push_current_line) (vimshell_insert_last_word) (vimshell_interrupt) (vimshell_delete_backward_char) (vimshell_delete_backward_char) (vimshell_delete_forward_line) VIMSHELL INTERACTIVE BUFFER KEY MAPPINGS *vimshell-interactive-buffer-key-mappings* Normal mode key mappings. *(vimshell_int_execute_line)* (vimshell_int_execute_line) Execute cursor line. *(vimshell_int_previous_prompt)* (vimshell_int_previous_prompt) Move to previous prompt from cursor. *(vimshell_int_next_prompt)* (vimshell_int_next_prompt) Move to next prompt from cursor. *(vimshell_int_paste_prompt)* (vimshell_int_paste_prompt) Paste cursor line to last prompt. (vimshell_int_hangup) *(vimshell_int_hangup)* Exit executing command. (vimshell_int_exit) *(vimshell_int_exit)* Exit interactive buffer. *(vimshell_int_restart_command)* (vimshell_int_restart_command) Restart command. *(vimshell_int_change_line)* (vimshell_int_change_line) Change whole line. *(vimshell_int_delete_line)* (vimshell_int_delete_line) Delete whole line. *(vimshell_int_insert_enter)* (vimshell_int_insert_enter) *(vimshell_int_insert_head)* (vimshell_int_insert_head) *(vimshell_int_append_enter)* (vimshell_int_append_enter) *(vimshell_int_append_end)* (vimshell_int_append_end) Enter insert mode. (vimshell_int_clear) *(vimshell_int_clear)* Redraw interactive buffer. Insert mode key mappings. *i_(vimshell_int_move_head)* (vimshell_int_move_head) Move to line head. *i_(vimshell_int_delete_backward_line)* (vimshell_int_delete_backward_line) Delete backward line from cursor. *i_(vimshell_int_delete_backward_word)* (vimshell_int_delete_backward_word) Delete backward word from cursor. *i_(vimshell_int_execute_line)* (vimshell_int_execute_line) Execute current line. *i_(vimshell_int_delete_backward_char)* (vimshell_int_delete_backward_char) *i_(vimshell_int_another_delete_backward_char)* (vimshell_int_another_delete_backward_char) Delete backward character from cursor. *i_(vimshell_int_send_input)* (vimshell_int_send_input) Send user input. *i_(vimshell_int_interrupt)* (vimshell_int_interrupt) Send interrupt to command. *i_(vimshell_int_command_complete)* (vimshell_int_command_complete) Start completion. *i_(vimshell_int_delete_forward_line)* (vimshell_int_delete_forward_line) Delete forward line from cursor. *i_(vimshell_int_history_unite)* (vimshell_int_history_unite) Execute vimshell history by unite interface. Note: To use it, you must install |unite.vim| plugin. *vimshell_int_default_key_mappings* Normal mode default key mappings. {lhs} {rhs} -------- ----------------------------- (vimshell_int_previous_prompt) (vimshell_int_next_prompt) (vimshell_int_execute_line) (vimshell_int_paste_prompt) (vimshell_int_restart_command) (vimshell_int_interrupt) q (vimshell_int_exit) cc (vimshell_int_change_line) dd (vimshell_int_delete_line) I (vimshell_int_insert_head) A (vimshell_int_append_end) i (vimshell_int_insert_enter) a (vimshell_int_append_enter) (vimshell_int_clear) *i_vimshell_int_default_key_mappings* Insert mode default key mappings. {lhs} {rhs} -------- ----------------------------- (vimshell_int_delete_backward_char) (vimshell_int_delete_backward_char) (vimshell_int_move_head) (vimshell_int_delete_backward_line) (vimshell_int_delete_backward_word) (vimshell_int_delete_forward_line) (vimshell_int_execute_line) (vimshell_int_interrupt) (vimshell_int_history_unite) (vimshell_int_send_input) Select candidate or start completion ------------------------------------------------------------------------------ FUNCTIONS *vimshell-functions* vimshell#get_status_string() *vimshell#get_status_string()* Returns vimshell status string. It is useful to custom statusline. vimshell#set_execute_file({exts}, {command}) *vimshell#set_execute_file()* Defines file execution command when it has {exts}. {exts} is comma separated file extensions. {command} is command arguments. (See: |g:vimshell_execute_file_list|) *vimshell#interactive#send()* vimshell#interactive#send({expr}) It sends {expr} to the interpreter in background buffer of vimshell, iexe, texe. You can control interpreter as if you are using |quickrun|. {expr} is string or list. Note: If interpreter is not loaded in current tab, you can run interpreter command. *vimshell#interactive#send_string()* vimshell#interactive#send_string({expr}) Deprecated. Use |vimshell#interactive#send()| instead; they are equivalent. vimshell#hook#set({hook-point}, {func-list}) *vimshell#hook#set()* Defines hook functions {func-list} in {hook-point}. The old hook points are overwrite. Vimshell call {func-list} by list order. vimshell#hook#get({hook-point}) *vimshell#hook#get()* Returns {hook-point} hook as dictionary. *vimshell#hook#add()* vimshell#hook#add({hook-point}, {hook-name}, {func}) Adds {hook-name} hook {func} in {hook-point}. If {hook-name} already exists, overwrite it. *vimshell#hook#remove()* vimshell#hook#remove({hook-point}, {hook-name}) Deletes {hook-name} function in {hook-point}. ------------------------------------------------------------------------------ OPTIONS *vimshell-options* {options} are options for a vimshell buffer. You may give the following parameters for an option; you must escape with "\" when it contains spaces. *vimshell-options-buffer-name* -buffer-name={buffer-name} Specifies a buffer name. The default buffer name is 'default'. Note: Buffer name must not contain spaces. *vimshell-options-toggle* -toggle Close vimshell buffer window if this vimshell buffer name window is exists. *vimshell-options-create* -create Create new vimshell buffer. *vimshell-options-split* -split Split vimshell buffer window. And |vimshell-options-split-command| is used. *vimshell-options-popup* -popup Popup split vimshell buffer window. |vimshell-options-split-command| is used. *vimshell-options-split-command* -split-command={command-name} Specify split command. *vimshell-options-prompt* -prompt={prompt} Specify prompt string. If omit it, |g:vimshell_prompt| is used. *vimshell-options-prompt_expr* -prompt_expr={expr} Specify prompt expression. If omit it, |g:vimshell_prompt_expr| is used. *vimshell-options-prompt_pattern* -prompt_pattern={expr} Specify prompt pattern. If omit it, |g:vimshell_prompt_pattern| is used. *vimshell-options-secondary-prompt* -secondary-prompt={secondary-prompt} Specify secondary prompt string. If omit it, |g:vimshell_secondary_prompt| is used. *vimshell-options-user-prompt* -user-prompt={user-prompt} Specify secondary prompt string. If omit it, |g:vimshell_user_prompt| is used. *vimshell-options-right-prompt* -right-prompt={right-prompt} Specify right prompt string. If omit it, |g:vimshell_right_prompt| is used. *vimshell-options-project* -project Move to project directory. *vimshell-options-quit* -quit Quit buffer after command finished. If |vimshell-options-popup| is enabled, switch to previous window. ============================================================================== EXAMPLES *vimshell-examples* > let g:vimshell_user_prompt = 'fnamemodify(getcwd(), ":~")' "let g:vimshell_right_prompt = 'vcs#info("(%s)-[%b]", "(%s)-[%b|%a]")' if has('win32') || has('win64') " Display user name on Windows. let g:vimshell_prompt = $USERNAME."% " else " Display user name on Linux. let g:vimshell_prompt = $USER."% " endif " Initialize execute file list. let g:vimshell_execute_file_list = {} call vimshell#set_execute_file('txt,vim,c,h,cpp,d,xml,java', 'vim') let g:vimshell_execute_file_list['rb'] = 'ruby' let g:vimshell_execute_file_list['pl'] = 'perl' let g:vimshell_execute_file_list['py'] = 'python' call vimshell#set_execute_file('html,xhtml', 'gexe firefox') autocmd FileType vimshell \ call vimshell#altercmd#define('g', 'git') \| call vimshell#altercmd#define('i', 'iexe') \| call vimshell#altercmd#define('l', 'll') \| call vimshell#altercmd#define('ll', 'ls -l') \| call vimshell#hook#add('chpwd', 'my_chpwd', 'MyChpwd') function! MyChpwd(args, context) call vimshell#execute('ls') endfunction autocmd FileType int-* call s:interactive_settings() function! s:interactive_settings() endfunction < ============================================================================== INTERNAL COMMANDS *vimshell-internal-commands* The internal commands are internal commands in other shells. The arguments are split by vimshell. Note: The internal commands do not supports pipeline. If you use pipe, vimshell execute external command forcibly. So following commands will be freeze. > vimshell% echo hello | vim < bg [{option}...] {command} *vimshell-internal-bg* Opens new buffer and executes {command} by background. Execute external command forcibly. You cannot input to {command}. If you press in background buffer, kill {command} execution. If {command} is not executable file, |g:vimshell_execute_file_list| is used. Note: "command &" equals to "bg command" > vimshell% ls& < Note: iexe, exe, bg, texe and less interpret options changes the behavior. Refer to |vimshell-execute-options|. --filetype={filetype-name} Changes output buffer 'filetype' to {filetype-name}. If omit the option, filetype will be set "background". --split={split-command} Specify split command. If omit this option, used |g:vimshell_split_command|. build [{builder-name}, [{args}...]] *vimshell-internal-build* Execute ":Unite build:{builder-name}:{args}". If you omit {builder-name}, detect builder automatically. cd {directory-path} [{substitute-pattern}] *vimshell-internal-cd* Changes the current directory to {directory-path}. If omit arguments, change the current directory to $HOME. If you set {substitute-pattern}, substitute {directory-path} to {substitute-pattern}. If {directory-path} is not a directory, change to file parent directory. If {directory-path} is not found, search 'cdpath'. If {directory-path} starts "-", same to |vimshell-internal-popd|. cdup {parent-directory-name} *vimshell-internal-cdup* Changes the current directory to the ancestor directory named as {parent-directory-name}. {parent-directory-name} is searched by substring match. It omit arguments, change the current directory to the parent directory. clear *vimshell-internal-clear* Clear display. dirs [{max}] *vimshell-internal-dirs* Print directory stack items to {max} . If omit {max}, used 10. If press in directory stack, change the directory. echo [{argument}...] *vimshell-internal-echo* print arguments. eval {expression} *vimshell-internal-eval* Eval {expression} as vimshell script and print it. *vimshell-internal-export* export [{variable-name}={value} , ...] Change {variable-name} environment variable to {value}. If the arguments is empty, print current environment variables. You can use this command like other shells. exe [{option}...] {command} *vimshell-internal-exe* Execute {command} with arguments. Execute the external command forcibly. Note: While executing commands, cannot execute other commands. Note: After vimshell Ver.9, exe can read inputs. Note: iexe, exe, bg, texe and less interpret options changes the behavior. Refer to |vimshell-execute-options|. *vimshell-execute-options* --encoding={encoding-name} *vimshell-execute-options-encoding* If different from 'encoding' and {encoding-name}, vimshell will convert encoding automatically. If omit this option, used "char". exit *vimshell-internal-exit* Exit vimshell buffer. gcd [{directory-path}] *vimshell-internal-gcd* Changes current directory and Vim current directory. If omit {directory-path}, move to Vim current directory. gendoc {command} {args} *vimshell-internal-gendoc* Executes {command} with {args} and saves output in "g:vimshell_data_directory/cached-doc". You can read cached outputs using |echodoc|. Note: This command caches first output line only. gexe {command} *vimshell-internal-gexe* Execute {command} with args. Execute the external command forcibly. Different from exe, it is specialized GUI command. h [{pattern}] *vimshell-internal-h* Executes {pattern} matched history. If {pattern} is number, execute {pattern} number history. If {pattern} is string, execute first {pattern} matched history. You can check history number by executing |vimshell-internal-history|. If you omit {pattern}, execute last command. Note: This command does not add history. Note: "![{pattern}]" or "!!" equals to "h" command" > vimshell% ! # Execute previous command. vimshell% !2 # Execute history number 2 command. vimshell% !! # Execute previous command. vimshell% !ls # Execute "ls" matched command. < histdel {history-number} *vimshell-internal-histdel* Deletes {history-number} history. You can check history number using |vimshell-internal-history| command. history [{search-string}] *vimshell-internal-history* Print directory stack {search-string} items. If omit {search-string}, use 20. If {search-string} is string, print matched string candidates. If press in history list, execute the history. iexe [{options}...] {command} *vimshell-internal-iexe* Opens new interactive buffer and execute {command} with args. Execute external command forcibly. Different from exe, this command is for interactive command. Note: Interactive buffer |filetype| is int-{command}. If you use |:autocmd| for interactive buffer, use "int-*" pattern. Note: This command does not support zsh's right-side prompt. If you execute a process from iexe, this sets "$VIMSHELL" 1. You may want to check it in your shell's rc file. Note: iexe, exe, bg, texe and less interpret options to change their behaviours. Refer |vimshell-execute-options|. --split={split-command} Specifies split command. If you omit this option, this uses |g:vimshell_split_command|. less [{options}...] {command} *vimshell-internal-less* Opens new buffer and executes {command} with arguments. Execute external command forcibly. Vimshell will work like pager. Note: syntax sugar: {command1} | {command2} | less If {command} is not executable command, execute |vimshell-internal-view|. Note: iexe, exe, bg, texe and less interpret options changes the behavior. Refer to |vimshell-execute-options|. --split={split-command} Specify split command. If omit this option, used |g:vimshell_split_command|. ls [{argument}...] *vimshell-internal-ls* Execute "ls" external command with args. Note: Required external "ls" command. mkcd {directory-name} *vimshell-internal-mkcd* Make {directory-name} directory and |vimshell-internal-cd| it. nop *vimshell-internal-nop* No operation. open {filename} *vimshell-internal-open* Open {filename} by associated application. popd [{directory-stack-number}] *vimshell-internal-popd* Change current directory to {directory-stack-number} directory. To view {directory-stack-number}, use |vimshell-internal-dirs|. If omit {directory-stack-number}, used 0. Note: If different from other shells, do not remove not duplicated candidates. pwd *vimshell-internal-pwd* Print vimshell working directory. repeat {cnt} {command} *vimshell-internal-repeat* Execute {command} {cnt} times. shell *vimshell-internal-shell* Execute 'shell' commands using |g:vimshell_use_terminal_command|. This command can support some features not supported vimshell. Ex: signal and trap. source {files} *vimshell-internal-source* Load {files} using "cmd.exe" in Windows, 'shell' in others. The {files} is shell script which changes environment variables. After executed the command, vimshell will use changed environment variables. Note: This internal command is for ":source file" only. Note: This internal command is not used for virtualenv. Because virtualenv uses shell function. source_shellcmd {shellcmd} [{args}] *vimshell-internal-source_shellcmd* Load {shellcmd} using "cmd.exe" in Windows, 'shell' in others. The {shellcmd} is shell command which changes environment variables. After executed the command, vimshell will use changed environment variables. Note: The {shellcmd} must be executable from |system()|. You may edit .zshenv/.bashenv. sudo {command} [{args}] *vimshell-internal-sudo* Execute super user command. If {command} is "vim", this uses |sudo.vim|. http://www.vim.org/scripts/script.php?script_id=729 On Windows, "sudo.exe" is necessary. http://bitbucket.org/wantora/sudo/wiki/Home texe [{options}...] {command} *vimshell-internal-texe* Execute {command} with args. Note: Execute external command forcibly. Different from exe and iexe, it executes terminal command. This command creates new buffer. Note: Pipe is not supported. Note: This command is under construction. Note: iexe, exe, bg, texe and less interpret options changes the behavior. Refer to |vimshell-execute-options|. --split={split-command} Specify split command. If omit this option, used |g:vimshell_split_command|. time {command} *vimshell-internal-time* Runs {command} synchronously and shows how long did it take. view [{options}...] {filenames}... *vimshell-internal-view* Opens {filenames} in other buffer as readonly. If lines is less than window size, do not open another buffer. --split={split-command} Specify split command. If omit this option, used |g:vimshell_split_command|. vi [{options}...] [{filenames}...] *vimshell-internal-vi* Same as |vimshell-internal-vim|. vim [{options}...] [{filenames}...] *vimshell-internal-vim* Opens {filenames} in other buffer. If omit {filenames}, opens unnamed buffer. --split={split-command} Specify split command. If omit this option, used |g:vimshell_split_command|. vimdiff {filename1} {filename2} *vimshell-internal-vimdiff* Compares {filename1} and {filename2} by |:vimdiff| command. --split={split-command} Specify split command. If omit this option, used |g:vimshell_split_command|. vimsh [{filename}] *vimshell-internal-vimsh* Execute {filename} vimshell script file. Note: Statements is not supported. If omit {filename}, opens new vimshell buffer. which {command} *vimshell-internal-which* Print {command} as full path. The command supports alias. whereis {command} *vimshell-internal-whereis* Print {command} by full path. ============================================================================== SPECIAL COMMANDS *vimshell-special-commands* Special command is minimum parsed by vimshell. So, you can parse arguments in special commands. But parsing is difficult. alias {alias-name} = {command} *vimshell-special-alias* Defines alias. Vimshell replaces {alias-name} as {command}. Different from other shells, "=" with spaces is valid. The alias can take arguments. To get arguments, use $$args variable. > vimshell% alias echo=':echo "$$args"' vimshell% alias echo2=':echo "$$args[1]"' vimshell% alias echo3=':echo "$$args[2:]"' < galias {global-alias-name} = {command} *vimshell-internal-galias* Defines global alias. Vimshell replaces {global-alias-name} as {command}. Different from |vimshell-special-alias|, global alias in arguments is expanded. This feature is like to zsh global alias. Note: Global alias with pipes is not supported. > vimshell% galias G = '|grep' vimshell% ls G hoge < let ${var-name} = {expression} *vimshell-special-let* Assigns {expression} to {var-name}. You must add prefix "$" in {var-name} head. Note: Shell variable is vimshell buffer local. To assign to environment variables, Capitalize variable name head. > vimshell% let $Hoge = $hoge < Different from other shells, "=" with spaces is valid. The {expression} is Vim script expression. But, you must add prefix "$" in variable name head. Executed status is write in "$$status". The prefix "$$" means vimshell internal variables. sexe {command} *vimshell-special-sexe* Execute {command} in 'shell'. If the command is wrong in vimshell, you can use this command. Note: Must be set 'shell' and shell options. Note: In windows, appears DOS window. vexe {expression} *vimshell-special-vexe* Execute {expression} as Vim script statement and prints outputs. You can use prefix ":" instead of vexe. Note: If you use ":", vimshell do not parse anything. --insert Start insert mode after execute {expression}. If omit the option, leave insert mode. Example: > :ls :e {some_file} < ============================================================================== ALTER COMMAND *vimshell-alter-command* Vimshell supports altercmd. Altercmd is like abbrev alias. Original altercmd plugin is here: [http://github.com/kana/vim-altercmd] To use altercmd, call |vimshell#altercmd#define| function in vimshell buffer. Usually, used in autocmd FileType. > autocmd FileType vimshell \ call vimshell#altercmd#define('g', 'git') < ============================================================================== HOOK *vimshell-hook* Vimshell has not function feature, but can call hook function in hook points. So If you learned Vim script and vimshell, customizable vimshell. Next examples set hook in "chpwd". This hook execute ls internal command when current directory is changed. > autocmd FileType vimshell \ call vimshell#hook#add('chpwd', 'my_chpwd', 'MyChpwd') function! MyChpwd(args, context) call vimshell#execute('ls') endfunction < Default hook points are below. Hook functions arguments are {args} and {context}. {args} is arguments list, {context} is context information. But some functions arguments is {cmdline}. chpwd *vimshell-hook-chpwd* This hook called when changed vimshell current directory. The first argument is new current directory. preparse *vimshell-hook-preparse* This hook called when before parse command line. The first argument is {cmdline}. {cmdline} is command line string. And returns changed command line string. preexec *vimshell-hook-preexec* This hook called when after alias parsed and before execute command line. The first argument is {cmdline}. {cmdline} is command line string. And returns changed command line string. postexec *vimshell-hook-postexec* This hook called when after execute command line. The first argument is {cmdline}. {cmdline} is executed command line string. emptycmd *vimshell-hook-emptycmd* This hook called when cmdline is empty. The first argument is {cmdline}. {cmdline} is command line string. And returns changed command line string. notfound *vimshell-hook-notfound* This hook called when the command is not found. The first argument is {cmdline}. {cmdline} is command line string. And returns changed command line string. preprompt *vimshell-hook-preprompt* This hook called when after execute command line and before display prompt. preinput *vimshell-hook-preinput* This hook called when after user input. The first argument is {input}. {input} is user input string. And returns changed input string. Note: This hook is usually used in interactive buffer. postinput *vimshell-hook-postinput* This hook called when after executed user input. The first argument is {input}. {input} is user input string. Note: This hook is usually used in interactive buffer. postexit *vimshell-hook-postexit* This hook called when after (external) command exit. The first argument is {command}. {command} is executed command name. The second argument is {cmdline}. {cmdline} is executed command line. You can get exit value by "b:vimshell.system_variables['status']". Note: This hook is usually used in interactive buffer. Note: The buffer may be deleted (or closed) in interactive buffer. To analyze command line, use |vimproc#parser#split_args()| or |vimproc#parser#split_args_through()|. These functions arguments are the command line string. |vimproc#parser#split_args()| evals quoted string, but |vimproc#parser#split_args_through()| remains quoted string. Note: These functions do not analyze ";", "&&", "||", pipes and redirection. ============================================================================== TIPS *vimshell-tips* directory stack *vimshell-tips-directory-stack* Vimshell supports directory stack like bash or zsh. And auto_pushd automatically. So, pushd command does not exist. To view directory stack, use |vimshell-internal-dirs|. To cd from directory stack, use |vimshell-internal-popd|. "cd -" is also supported. auto_cd *vimshell-tips-auto_cd* Vimshell supports auto_cd like zsh. If you execute with a directory name, vimshell moves to the current directory. Note: The setting is nothing. block *vimshell-tips-block* Vimshell supports Block. > vimshell% echo /hoge/piyo/{hoge,hogera} -> /hoge/piyo/hoge /hoge/piyo/hogera < And supports expanding numbers feature. > vimshell% echo {00..09} -> 00 01 02 03 04 05 06 07 08 09 < wild card *vimshell-tips-wildcard* Vimshell supports wildcard. If wildcard files are not found, an error is occurred. > vimshell% ls *.htm < Ignore pattern is supported. > vimshell% ls *~*.htm < backquote *vimshell-tips-backquote* You can use command output as arguments. > vimshell% echo `ls` < Backquote works in double quoted string. > vimshell% python -c "`curl -fs https://gist.github.com/raw/4349265/sudden-vim.py`" < And embed Vim script expression. > vimshell% echo `=3` < fakecygpty *vimshell-tips-fakecygpty* fakecygpty connects Windows pipes to Cygwin pty. Note: This command is only on Windows. Following command is to connect to Cygwin ssh command. > > fakecygpty ssh < fakecygpty original source code is in Meadow. But I distribute the source. http://github.com/Shougo/fakecygpty To compile the source code, execute the command below. > $ gcc fakecygpty.c -o fakecygpty.exe < And put fakecygpty command in $PATH directory. > encoding *vimshell-tips-encoding* If you set 'encoding' manually on Windows environment, multibyte characters may be broken. But some commands on Windows are using "utf8" characters. If you use that commands, use command "--encoding" option. > vimshell% iexe --encoding=utf8 ghci < environment-variables-execution *vimshell-tips-environment-variables-execution* To execute commands with changing environment variables like sh's "env=value command" syntax, you can use "env" command. Example: > :call vimproc#system('env GIT_EDITOR= git commit') < auto-jump *vimshell-tips-auto-jump* You can use auto jump behavior by using alias. Example: > call vimshell#set_alias('j', ':Unite -buffer-name=files \ -default-action=lcd -no-split -input=$$args directory_mru') < ============================================================================== UNITE SOURCES *vimshell-unite-sources* *vimshell-unite-source-vimshell-history* vimshell/history Nominates vimshell histories as candidates. This source is also available on interactive buffer. This source is used in |unite#sources#vimshell_history#start_complete()|. Note: Default mapping is . Example: > inoremap \ unite#sources#vimshell_history#start_complete() < *vimshell-unite-source-vimshell-external_history* vimshell/external_history Nominates external shell histories as candidates. This source is also available in interactive buffer. This source is used in |unite#sources#vimshell_history#start_complete()|. Note: Edit histories is invalid. Vimshell searches external history path from $SHELL automatically. You can set external history path |g:unite_source_vimshell_external_history_path|. kind actions: vimshell/history *vimshell-unite-action-vimshell-history* execute Execute history. If you selected several histories, it joins with "; ". edit Edit history. delete Delete history. ============================================================================== CREATE PLUGIN *vimshell-create-plugin* In this clause, I comment on a method to make plugin of vimshell. The ability of vimshell will spread by creating plugin by yourself. You can add a new vimshell command easily just by adding a plugin file under autoload/internal/ directory; vimshell reads *.vim files there as internal command. A tutorial is available (in Japanese.) http://yomi322.hateblo.jp/entry/2013/01/13/141003 ============================================================================== FAQ *vimshell-faq* Q: I want to yank text without escape sequences. A: You can use |concealedyank.vim| plugin. https://github.com/chikatoike/concealedyank.vim (operator-concealedyank) yanks text without concealed text. > xmap Y (operator-concealedyank) < Q: I want to add paths to $PATH. A: You can add them by writing a line like below in .vimshrc. Note: That any Environment constant inside the double quotes will not be unfold. > let $PATH="~/bin:/local/usr/bin:/".$PATH < Q: Why vimshell does not support "\" path separator in Windows? https://github.com/Shougo/vimshell/issues/86 A: Because we would love to provide compatibility between Windows and UNIX with same script. The path separator is just an evil shit. Q: I want to change |g:vimshell_prompt| dynamically. A: You cannot do it. |g:vimshell_prompt| is fixed string. But you can change |g:vimshell_prompt_expr| or |g:vimshell_user_prompt| dynamically instead of it. Q: I want to execute history by completion interface. A: You can use |(vimshell_history_neocomplete)| mapping. Note: |neocomplete| is required. > imap (vimshell_history_neocomplete) < Q: vimshell does not use escape sequence color. A: To use escape sequence, you must enable |+conceal| feature. It is only Vim 7.3 or above. ============================================================================== vim:tw=78:ts=8:ft=help:norl:noet:fen:isk+=-: