Commands
********

This section is a semi-automatically bowdlerized version of the Vi reference created by
 maart@cs.vu.nl and others. It can be found on the Vi archives. Very little has been changed for VIP.

Groundwork
==========

The VI command set is based on the idea of combining motion commands with other commands. The motion command is used as a text region specifier for other commands. We classify motion commands into point commands and line commands.

The point commands are:

     h, l, 0,  $, w, W, b, B, e, E, (, ), /, ?, `, f, F, t, T, %, ;, ,, ^

The line commands are:

     j, k, +, -, H, M, L, {, }, G, ',  [[, ]], []

Text Deletion Commands (see Deleting Text.), Change commands (see Changing Text.), even Shell Commands (see Shell Commands) use these commands to describe a region of text to operate on.

VIP adds the two region descriptors, r and R. These describe the Emacs regions (see Basics), but are not movement commands.

The command description uses angle brackets <> to indicate metasyntactic variables, since the normal conventions of using simple text can be confusing with VIP where the commands themselves are characters. Watch out where < shift commands and <count> are mentioned together!!!.

<move> refers to the above movement commands, and <a-z> refers to registers or textmarkers from a to z. Note that the <move>  is described by full move commands, that is to say they will take counts, and otherwise behave like normal move commands. <address> refers to Ex line addresses, which include

. <No address>
     Current line

.+n .-n
     Add or subtract for current line

number
     Actual line number, use .= to get the line number

'<a-z>
     Textmarker

$
     Last line

x,y
     Where x and y are one of the above

%
     For the whole file, same as (1,$).

/pat/ ?pat?
     Next or previous line with pattern pat

Note that % is used in Ex commands to mean current file. If you want a % in your command, it must be escaped as \%. Similarly, # expands to the previous file. The previous file is the first file in :args listing. This defaults to previous window in the VI sense if you have one window only.

Others like <args> -- arguments, <cmd> -- command etc. should be fairly obvious.

Common characters referred to include:

<sp>
     Space

<ht>
     Tab

<lf>
     Linefeed

<esc>
     Escape

<cr>
     Return, Enter

We also use word for alphanumeric/non-alphanumeric words, and WORD for whitespace delimited words. char refers to any ascii character, CHAR to non-whitespace character. Brackets [] indicate optional parameters; <count> also optional, usually defaulting to 1. Brackets are elided for <count> to eschew obfuscation.

The usual Emacs convention is used to indicate Control Characters, i.e C-h for Control-h. Do not confuse this to mean the separate characters C - h!!!. The ^ is itself, never used to indicate a Control character.

Text Handling
=============

Move Commands
-------------

<count>  h  C-h
     <count> chars to the left.

<count>  j  <lf> C-n
     <count> lines downward.

<count>  l  <sp>
     <count> chars to the right.

<count>  k  C-p
     <count> lines upward.

<count>  $
     To the end of line <count> from the cursor.

<count>  ^
     To the first CHAR <count> - 1 lines lower.

<count>  -
     To the first CHAR <count> lines higher.

<count>  +  <cr>
     To the first CHAR <count> lines lower.

0
     To the first char of the line.

<count> |
     To column <count>

<count>  f<char>
     <count> <char>s to the right (find).

<count>  t<char>
     Till before <count> <char>s to the right.

<count>  F<char>
     <count> <char>s to the left.

<count>  T<char>
     Till after <count> <char>s to the left.

<count>  ;
     Repeat latest f t F T <count> times.

<count>  ,
     Repeat latest f t F T <count> times in opposite direction.

<count>  w
     <count> words forward.

<count>  W
     <count> WORDS forward.

<count>  b
     <count> words backward.

<count>  B
     <count> WORDS backward.

<count>  e
     To the end of word <count> forward.

<count>  E
     To the end of WORD <count> forward.

<count>  G
     Go to line <count> (default end-of-file).

<count>  H
     To line <count> from top of the screen (home).

<count>  L
     To line <count> from bottom of the screen (last).

M
     To the middle line of the screen.

<count>  )
     <count> sentences forward.

<count>  (
     <count> sentences backward.

<count>  }
     <count> paragraphs forward.

<count>  {
     <count> paragraphs backward.

<count>  ]]
     To the <count>th heading.

<count>  [[
     To the <count>th previous heading.

<count>  []
     To the end of <count>th heading.

m<a-z>
     Mark the cursor position with a letter.

`<a-z>
     To the mark.

'<a-z>
     To the first CHAR of the line with the mark.

[<a-z>
     Show contents of textmarker.

]<a-z>
     Show contents of register.

``
     To the cursor position before the latest absolute jump (of which are examples / and G).

''
     To the first CHAR of the line on which the cursor was placed before the latest absolute jump.

<count>  /<string>
     To the <count>th occurrence of <string>.

<count>  /<cr>
     To the <count>th occurrence of <string> from previous / or ?.

<count>  ?<string>
     To the <count>th previous occurrence of <string>.

<count>  ?<cr>
     To the <count>th previous occurrence of <string> from previous ? or /.

n
     Repeat latest / ? (next).

N
     Idem in opposite direction.

%
     Find the next bracket and go to its match.

Marking
-------

Emacs mark is referred to in the region specifiers r and R. See Emacs Preliminaries and see Basics for explanation. Also see Mark (The GNU Emacs manual), for an explanation of the Emacs mark ring.

m<a-z>
     Mark the current file and position with the specified letter.

m .
     Set the Emacs mark (see Emacs Preliminaries) at point.

m <
     Set the Emacs mark at beginning of buffer.

m >
     Set the Emacs mark at end of buffer.

m ,
     Jump to the Emacs mark.

``
     Exchange point and mark.

''
     Exchange point and mark and go to the first CHAR on line.

'<a-z>
     Go to specified VIP mark.

     Go to specified VIP mark and go to the first CHAR on line.

Appending Text
--------------

See Options to see how to change tab and shiftwidth size. See the GNU Emacs manual, or try C-ha tabs (If you have turned Emacs help on). Check out the variable indent-tabs-mode to put in just spaces. Also see options for word-wrap.

<count>  a
     <count> times after the cursor.

<count>  A
     <count> times at the end of line.

<count>  i
     <count> times before the cursor (insert).

<count>  I
     <count> times before the first CHAR of the line

<count>  o
     On a new line below the current (open). The count is only useful on a slow terminal.

<count>  O
     On a new line above the current. The count is only useful on a slow terminal.

<count>  ><move>
     Shift the lines described by <count><move> one shiftwidth to the right (layout!).

<count>  >>
     Shift <count> lines one shiftwidth to the right.

<count>  ["<a-z1-9>]p
     Put the contents of the (default undo) buffer <count> times after the cursor. The register will be automatically downcased.

<count>  ["<a-z1-9>]P
     Put the contents of the (default undo) buffer <count> times before the cursor. The register will

[<a-z>
     Show contents of textmarker.

]<a-z>
     Show contents of register.

<count>  .
     Repeat previous command <count> times. For destructive commands as well as undo.

Editing in Insert Mode
----------------------

The Minibuffer can be edited in the same way as Insert mode.

C-v
     Deprive the next char of its special meaning (quoting).

C-d
     One shiftwidth to the left.

0C-d
     Remove all indentation on the current line (there must be no other chars on the line).

^C-d
     Idem, but it is restored on the next line.

C-t
     one shiftwidth to the right

C-h
     One char back.

C-w
     One word back.

C-u
     Back to the begin of the change on the current line.

C-c
     like <esc>.

Deleting Text
-------------

<count>  x
     Delete <count> chars under and after the cursor.

<count>  X
     <count> chars before the cursor.

<count>  d<move>
     From begin to endpoint of <count><move>.

<count>  dd
     <count> lines.

D
     The rest of the line.

<count>  <<move>
     Shift the lines described by <count><move> one shiftwidth to the left (layout!).

<count>  <<
     Shift <count> lines one shiftwidth to the left.

Changing Text
-------------

<count>  r<char>
     Replace <count> chars by <char> - no <esc>.

<count>  R
     Overwrite the rest of the line, appending change COUNT - 1 times.

<count>  s
     Substitute <count> chars.

<count>  S
     <count> lines.

<count>  c<move>
     Change from begin to endpoint of <count><move>.

<count>  cc
     <count> lines.

<count>  C
     The rest of the line and <count> - 1 next lines.

<count>  =<move>
     Reindent the region described by move.

<count>  ~
     Switch lower and upper cases.

<count>  J
     Join <count> lines (default 2).

:[x,y]s/<p>/<r>/<f>
     Substitute (on lines x through y) the pattern <p> (default the last pattern) with <r>.  Useful flags <f> are g for global (i.e. change every non-overlapping occurrence of <p>) and c for confirm (type y to confirm a particular substitution, else n ).  Instead of / any punctuation CHAR unequal to <space> <tab> and <lf> can be used as delimiter.

&
     Repeat latest ex substitute command, e.g. :s/wrong/good.

#c<move>
     Change upper case characters in the region to lower case.

#C<move>
     Change lower case characters in the region to upper case.

#q<move>
     Insert specified string at the beginning of each line in the region

Search and Replace
------------------

See Groundwork, for Ex address syntax. See Options to see how to get literal (non-regular-expression) search and how to stop search from wrapping around.

<count>  /<string>
     To the <count>th occurrence of <string>.

<count>  ?<string>
     To the <count>th previous occurrence of <string>.

<count>  g<move>
     Search for the text described by move. (off by default)

n
     Repeat latest / ? (next).

N
     Idem in opposite direction.

%
     Find the next bracket and go to its match

:[x,y]g/<string>/<cmd>
     Search globally [from line x to y] for <string> and execute the ex <cmd> on each occurrence.

:[x,y]v/<string>/<cmd>
     Execute <cmd> on the lines that don't match.

#g<move>
     Execute the last keyboard macro for each line in the region. See Macros and Registers, for more info.

Q
     Query Replace.

:ta <name>
     Search in the tags file where <name> is defined (file, line), and go to it.

:[x,y]s/<p>/<r>/<f>
     Substitute (on lines x through y) the pattern <p> (default the last pattern) with <r>.  Useful flags <f> are g for global (i.e. change every non-overlapping occurrence of <p>) and c for confirm (type y to confirm a particular substitution, else n).  Instead of / any punctuation CHAR unequal to <space> <tab> and <lf> can be used as delimiter.

&
     Repeat latest ex substitute command, e.g. :s/wrong/good.

Yanking
-------

<count>  y<move>
     Yank from begin to endpoint of <count><move>.

<count>  "<a-z>y<move>
     Yank from begin to endpoint of <count><move> to register.

<count>  "<A-Z>y<move>
     Yank from begin to endpoint of <count><move> and append to register.

<count>  yy
     <count> lines.

<count>  Y
     Idem (should be equivalent to y$ though).

m<a-z>
     Mark the cursor position with a letter.

[<a-z>
     Show contents of textmarker.

]<a-z>
     Show contents of register.

<count>  ["<a-z1-9>]p
     Put the contents of the (default undo) buffer <count> times after the cursor. The register will be automatically downcased.

<count>  ["<a-z1-9>]P
     Put the contents of the (default undo) buffer <count> times before the cursor. The register will

Undoing
-------

u U
     Undo the latest change.

.
     Repeat undo.

:q!
     Quit vi without writing.

:e!
     Re-edit a messed-up file.

:rec
     recover file from autosave. VIP also creates backup files that have a ~ appended to them.

Display
=======

C-g
     Give file name, status, current line number and relative position.

C-l
     Refresh the screen.

<count> C-e
     Expose <count> more lines at bottom, cursor stays put (if possible).

<count> C-y
     Expose <count> more lines at top, cursor stays put (if possible).

<count> C-d
     Scroll <count> lines downward (default the number of the previous scroll; initialization: half a page).

<count> C-u
     Scroll <count> lines upward (default the number of the previous scroll; initialization: half a page).

<count> C-f
     <count> pages forward.

<count> C-b
     <count> pages backward (in older versions C-b only works without count).

<count> z<cr> zH
     Put line <count> at the top of the window (default the current line).

<count> z- zL
     Put line <count> at the bottom of the window (default the current line).

<count> z. zM
     Put line <count> in the center of the window (default the current line).

File Handling
=============

:q
     Quit buffer except if modified.

:q!
     Quit buffer without checking.

:susp :stop
     Suspend VIP

:w
     Write the file.

:w <name>
     Write to the file <name>.

:w >> <name>
     Append the buffer to the file <name>.

:w! <name>
     Overwrite the file <name>.

:x,y w <name>
     Write lines x through y to the file <name>.

:wq
     Write the file and kill buffer.

ZZ
     Save buffers and kill Emacs.

:x [<file>]
     Save and kill buffer.

:x! [<file>]
     :w![<file>] and :q.

:pre
     Preserve the file - autosave buffers.

:rec
     recover file from autosave.

:f
     Print file name and lines.

:cd [<dir>]
     Set the working directory to <dir> (default home directory).

:pwd
     Print present working directory.

:e [+<cmd>] <files>
     Edit files. If no filename is given, dired current directory.

:q!
     Quit vi without writing.

:e!
     Re-edit a messed-up file.

:e! [+<cmd>] <files>
     Edit file. If no filename, reedit current file.

C-^
     Edit the alternate (normally the previous) file.

:rew
     Obsolete

:args
     List files not shown anywhere with counts for next

:n [count]  [+<cmd>] [<files>]
     Edit <count> file, or edit files. The count comes from :args

:<address>r <name>
     Read the file <name> into the buffer after the line <address>.

v V
     Edit a file in current or another window. File name is typed in minibuffer.

Mapping
=======

:map <char> <seq>
     <char> is interpreted as <seq> `:map C-c :!wc %' to run wc on current file. (vi replaces % with the current file name).

:unmap <char>
     Deprive <char> of its mappings.

:map! <char> <seq>
     Mapping in Insert mode.

:unmap! <char>
     Deprive <string> of its mapping (see :unmap).

@<a-z>
     Execute the contents of register as a command.

@@
     Repeat last register command.

@#
     Begin keyboard macro. End with @<a-z>. This will put the macro in the proper register. Register will be automatically downcased. See Macros and Registers, for more info.

@!<a-z>
     Yank anonymous macro to register

*
     Execute anonymous macro (defined by C-x( and C-x )).

#g<move>
     Execute the last keyboard macro for each line in the region. See Macros and Registers, for more info.

[<a-z>
     Show contents of textmarker.

]<a-z>
     Show contents of register.

Shell Commands
==============

Note that % is used in Ex commands to mean current file. If you want a % in your command, it must be escaped as \%. However if % is the first character, it stands as the address for the whole file. Similarly, # expands to the previous file. The previous file is the first file in :args listing. This defaults to the previous file in the VI sense if you have one window.

:sh
     Execute a subshell in another window

:[x,y]!<cmd>
     Execute a shell <cmd> [on lines x through y; % is replace by current file, \% is changed to %

:[x,y]!! [<args>]
     Repeat last shell command [and append <args>].

:!<cmd>
     Just execute command and display result in a buffer.

:!! <args>
     Repeat last shell command and append <args>

<count> !<move><cmd>
     The shell executes <cmd>, with standard input the lines described by <count><move>, next the standard output replaces those lines (think of cb, sort, nroff, etc.).

<count> !!<cmd>
     Give <count> lines as standard input to the shell <cmd>, next let the standard output replace those lines.

:x,y w !<cmd>
     Let lines x to y be standard input for <cmd> (notice the <sp> between w and !).

:<address>r !<cmd>
     Put the output of <cmd> after the line <address> (default current).

:<address>r <name>
     Read the file <name> into the buffer after the line <address> (default current).

Options
=======

ai
     autoindent - In append mode after a <cr> the cursor will move directly below the first CHAR on the previous line.

ic
     ignorecase - No distinction between upper and lower cases when searching.

magic
     Regular expressions used in searches. nomagic means no regexps.

ro
     readonly - The file is not to be changed. However, :w! will override this option.

sh=<string>
     shell - The program to be used for shell escapes (default $SHELL (default /bin/sh)).

sw=<count>
     shiftwidth - Gives the shiftwidth (default 8 positions).

sm
     showmatch - Whenever you append a ), vi shows its match if it's on the same page; also with { and }.  If there's no match, vi will beep.

ts=<count>
     tabstop - The length of a <ht>; warning: this is only IN the editor, outside of it <ht>s have their normal length (default 8 positions).

wm=<count>
     wrapmargin - In append mode vi automatically puts a <lf> whenever there is a <sp> or <ht> within <wm> columns from the right margin.

ws
     wrapscan - When searching, the end is considered stuck to the begin of the file.

:set <option>
     Turn <option> on.

:set no<option>
     Turn <option> off.

:set <option>=<value>
     Set <option> to <value>.

Emacs Related Commands
======================

_
     Begin Meta command in Vi mode. Most often used as _x (M-x).

C-z
     Begin Meta command in Insert mode.

C-z
     Switch between Emacs and Vi modes.

C-x0
     Close Window

C-x1
     Close Other Windows

C-x2
     Split Window

C-xo
     Move among windows

C-xC-f
     Emacs find-file, useful in Insert mode