vi.txt

<p><em>Vi</em> (pronounced &quot;vee-eye&quot;) is a popular and very powerful text editor. It&#39;s fairly hard to learn, but it&#39;s well worth learning, especially since it&#39;s often the only editor available on an unfamiliar Unix system.</p>

<p>The first thing you&#39;ll notice about <em>vi</em> when you run it is that you can&#39;t enter text straight away. This is because <em>vi</em> starts in <em>command mode</em>, which uses many commands based on keys that would normally produce a character (such as letters and punctuation). This is an unusual approach but it works well as the majority of commands are single, unshifted keystrokes on the main part of the keyboard, meaning that for the vast majority of your time using <em>vi</em>, your hands stay in exactly the same place. This way you don&#39;t waste time moving your hands around the keyboard. Also, the rarity of commands using CTRL or ALT reduces the amount of stretching that the hand has to do, reducing the probability of repetitive strain injury.</p>

<h2>Modes</h2>

<p><em>Vi</em> has several modes; the most important are command mode, insert
mode, command line mode and visual mode. In any of these modes you can press <strong>ESC</strong>
to go back to command mode.</p>

<h3>Insert mode</h3>

<p>Insert mode behaves much as you&#39;d expect: pressing a key inserts the appropriate character. You can use the arrow keys to move about, but bear in mind that going back to command mode is often faster, especially if you have a long way to move.</p>

<p>There are several ways to enter insert mode from command mode. Most commonly you will press <strong>i</strong> to start typing before the cursor, or <strong>a</strong> to start typing after it. You can also press <strong>o</strong> or <strong>O</strong> to insert a blank line respectively after or before the current one and start typing in it.  (Note that vi is case sensitive.)</p>

<p>To leave insert mode, just press <strong>ESC</strong>.</p>

<h3>Command mode</h3>

<p>Most of your time will be spent in command mode. Here you enter commands to enter other modes, move the cursor around, and do simple text manipulation such as deleting (cutting), yanking (copying) and pasting.</p>

<p>In general, there are two types of command: those that are modified using a count, and those that are modified using a movement. Commands taking a count can be entered without one, but commands taking a movement don&#39;t do anything until they get a movement telling them how much text to act on.</p>

<p>As an exanple, there are two ways to delete 5 lines, and to delete 10 characters to the right of the cursor.</p>

<h4>Supplying a count</h4>

<p>To delete the current line and the four lines after it, press <strong>5dd</strong>. Similarly, to delete the current character and 9 characters to the right of it, press <strong>10x</strong>.</p>

<p>The exact meaning of the count depends on the command. For example, the <strong>K</strong> command looks up the word under the cursor in the <a href="../The%20Online%20Manual">manual</a> (exactly as if you had typed <strong>man (word)</strong> in the shell). Adding a count tells the command to look the word up in that section of the manual (exactly as if you had typed <strong>man (count) (word)</strong> in the shell).</p>

<h4>Combining a command with a movement</h4>

<p>Movement of the cursor is achieved using the keys h, j, k and l - these are left, down, up and right respectively. Think of the curve in the j as being an arrow pointing downwards. These are &quot;count&quot; commands - that is, they can be repeated by typing a number before it. You can also move the cursor using the arrow keys, but they can&#39;t be combined with commands as described below like hjkl can. There are also lots of advanced movement commands that move further, e.g. to the beginning / end of the word / sentence / paragraph. These are documented in <em>vim</em>&#39;s online help system (type <strong>:h</strong> to read it).</p>

<p>To delete the current line and the 4 lines after it, press <strong>d4j</strong>. In words, this means &quot;delete lines from here until wherever the movement <strong>4j</strong> goes&quot;. Similarly, <strong>d9l</strong> deletes the current character and the 9 characters to the right of it - it says &quot;delete characters from here until wherever the movement <strong>9l</strong> goes&quot;.</p>

<h4>Command mode reference</h4>

<table border="1" cellspacing="1" cellpadding="1" style="margin-top: 1em; margin-bottom: 1em">
<thead>
<tr><td>Command</td><td>Meaining</td><td>Modifier</td></tr>
</thead>
<tbody>
<tr><td>a</td><td>Append text after cursor (enters insert mode)</td><td>Count</td></tr>
<tr><td>d</td><td>Delete (cut) text</td><td>Movement</td></tr>
<tr><td>dd</td><td>Delete line</td><td>Count</td></tr>
<tr><td>D</td><td>Delete rest of line (if given count &gt; 1, also deletes count-1 following lines)</td><td>Count</td></tr>
<tr><td>gg</td><td>Move to start of file (or countth line)</td><td>Count</td></tr>
<tr><td>G</td><td>Move to end of file (or countth line)</td><td>Count</td></tr>
<tr><td>h</td><td>Move left</td><td>Count</td></tr>
<tr><td>i</td><td>Insert text before cursor (enters insert mode)</td><td>Count</td></tr>
<tr><td>j</td><td>Move down</td><td>Count</td></tr>
<tr><td>J</td><td>Join lines (minimum count 2, if specified)</td><td>Count</td></tr>
<tr><td>k</td><td>Move up</td><td>Count</td></tr>
<tr><td>l</td><td>Move right</td><td>Count</td></tr>
<tr><td>n</td><td>Repeat last search</td><td>Count</td></tr>
<tr><td>o</td><td>Insert text in a blank line after current line (enters insert mode)</td><td>Count</td></tr>
<tr><td>O</td><td>Insert text in a blank line before current line (enters insert mode)</td><td>Count</td></tr>
<tr><td>p</td><td>Paste after cursor</td><td>Count</td></tr>
<tr><td>P</td><td>Paste before cursor</td><td>Count</td></tr>
<tr><td>u</td><td>Undo (very useful!)</td><td>Count</td></tr>
<tr><td>CTRL-r</td><td>Redo</td><td>Count</td>
</tr><tr><td>v</td><td>Enter visual mode</td><td>Movement</td></tr>
<tr><td>V</td><td>Enter linewise visual mode</td><td>Movement</td></tr>
<tr><td>x</td><td>Delete character at cursor</td><td>Count</td></tr>
<tr><td>X</td><td>Delete character before cursor</td><td>Count</td></tr>
<tr><td>y</td><td>Yank (copy)</td><td>Movement</td></tr>
<tr><td>yy</td><td>Yank line</td><td>Count</td></tr>
<tr><td>/</td><td>Search forwards from cursor</td><td>Count</td></tr>
<tr><td>?</td><td>Search backwards from cursor</td><td>Count</td></tr>
<tr><td>:</td><td>Enter command-line mode</td><td>Count or Visual</td></tr>
<tr><td>&lt;</td><td>Shift line left count times</td><td>Count</td></tr>
<tr><td>&gt;</td><td>Shift line right count times</td><td>Count</td></tr>
<tr><td>&lt;&lt;</td><td>Shift line left once</td><td>None</td></tr>
<tr><td>&gt;&gt;</td><td>Shift line right once</td><td>None</td></tr>
<tr><td>%</td><td>Match brackets / braces etc (handy if you get lost among lots of parentheses)</td><td>None</td></tr>
<tr><td>^</td><td>Move to start of line (but after whitespace)</td><td>None</td></tr>
<tr><td>0</td><td>Move to start of line</td><td>None</td></tr>
<tr><td>$</td><td>Move to end of line</td><td>None</td></tr>
</tbody>
</table>

<h3>Command line mode</h3>

<p><em>Vi</em> has a &quot;command line&quot; which is used to enter a number of &quot;Ex  commands&quot; that have long names or take various textual arguments - for example, opening and saving files and setting variables. To enter an Ex command first press <strong>:</strong> (colon). There isn&#39;t much to say about this mode except to give a list of some commonly used commands.</p>

<table border="1" cellspacing="1" cellpadding="1">
<thead>
<tr><td>Command</td><td>Meaning</td></tr>
</thead>
<tbody>
<tr><td>e</td><td>Open a new file for editing - follow by filename</td></tr>
<tr><td>w</td><td>Save (write) - follow by filename to use (unless you want to save with the same filename)</td></tr>
<tr><td>q</td><td>Quit</td></tr>
<tr><td>wq</td><td>Save and quit</td></tr>
<tr><td>noh</td><td>Stop highlighting things found by the last search</td></tr>
<tr><td>syntax on</td><td>Turn syntax colouring on (<em>vim</em>-specific)</td></tr>
<tr><td>syntax off</td><td>Turn syntax colouring off (<em>vim</em>-specific)</td></tr>
<tr><td>set</td><td>Set an option</td></tr>
<tr><td>let</td><td>Set a variable</td></tr>
<tr><td>s/foo/bar/</td><td>Substitute regular expression foo with bar. Useful for changing large amounts of text at the same time or in the same way</td></tr>
<tr><td>h</td><td>Read <em>vim</em>&#39;s online help - optionally follow by a word to look up. (<em>vim</em>-specific, though probably works in some other versions)</td></tr>
</tbody>
</table>

<p>Sometimes it might be a bad idea to execute a command - for example, typing <strong>:q</strong> without saving first. In these cases <em>vi</em> might not let the command go ahead. You can override this using an exclamation mark; for example, <strong>:q!</strong> quits without saving, even if the buffer has changed since you last saved.</p>

<p>For commands that act on the current line only, the command can be preceded by % to make it act on every line instead. There are a few such range modifiers, all of which are documented in vim&#39;s online help.</p>

<h3>Visual mode</h3>

<p>This provides a convenient alternative to most movement-oriented commands rather like selection in other editors. Pressing <strong>v</strong> starts a highlight on the current character that can be expanded by moving about (with hjkl or other movement commands, but <em>not</em> the arrow keys). Similarly, pressing <strong>V</strong> selects text a line at a time, and moving up and down changes the amount of text selected.</p>

<p>For example, <strong>v9ld</strong> will delete the current character and the 9 to the right of it, but, equivalently, you can press <strong>v</strong>, then <strong>l</strong> nine times, followed by <strong>d</strong>. And <strong>V4jd</strong>, or <strong>V</strong> followed by <strong>j</strong> four times and then <strong>d</strong>, will delete the current line and the four lines after it. Between the <strong>v</strong> or <strong>V</strong> and the command, the text which the command will act on is highlighted.</p>

<p>To cancel visual mode, press <strong>ESC</strong>.</p>

<p>(Historical note: <em>vi</em> is an abbreviation for &quot;visual&quot;, but it wasn&#39;t named after this mode - rather, it was to distinguish it from line editors such as <em>ed</em> which were the only editors available when the original <em>vi</em> was created back in the early 1970s. They&#39;re not much used now because the hardcopy terminals they were designed for are long since obsolete.)</p>

<h3>Ex mode</h3>

<p>Ex mode is like command-line mode, except that you enter a sequence of Ex commands instead of directly working on the file. It&#39;s rather like <em>ed</em>. As such it is rather hard to use and not particularly useful.</p>

<h2>Some useful features in vim</h2>

<p>The following instructions refer only to vim; other clones may have similar mechanisms, but probably not the same ones.</p>

<h3>Syntax colouring</h3>

<p>Many clones of vi, including vim, provide highlighting of syntactic elements in a large number of programming and markup languages. This can greatly help in understanding the structure of code, especially if you are dyslexic.</p>

<p>To turn on syntax highlighting, type <strong>:syntax on</strong>. If you are using an appropriate filename (i.e. one that has the canonical extention for the language you are editing) vim will be able to guess which language you want. in some cases the guess is wrong - in these cases you can tell vim to highlight for a different language by typing <strong>:set syntax=(language)</strong>.</p>

<p>In particular, the filename extension .pl is, by default, associated with Perl. Unfortunately this clashes with the default extension for Prolog source files, which is also .pl. You can tell vim to interpret the file as Prolog by typing <strong>:set syntax=prolog</strong>.</p>

<p>Another thing to watch out for is that each syntax specification may support several dialects. For example, vim&#39;s Pascal highlighting supports GNU Pascal as well as Delphi. Generally you need to set a variable to change vim&#39;s behaviour in these cases:</p>

<ul>
<li>To highlight Pascal using Delphi&#39;s dialect, type <strong>:let pascal_delphi = 1</strong></li>
<li>To highlight Bourne shell scripts using the bash dialect, type <strong>:let is_bash = 1</strong></li>
</ul>

<h3>Autoindent and c-indent</h3>

<p>These are two exceptionally handy features when editing source code:</p>

<ul>
<li>Autoindent (turned on with <strong>:set ai</strong> and turned off with <strong>:set noai</strong>) automatically inserts as much whitespace at the start of a new line as there is on the current line (e.g. when you press enter or use the <strong>o</strong> or <strong>O</strong> commands). This saves you reaching for the tab key most of the time.</li>
<li>C-indent (turned on with <strong>:set cin</strong> and turned off with <strong>:set nocin</strong>) provides even more when editing C source code (and source code for languages with C-like syntax, such as Java). On top of the provisions of autoindent, it automatically inserts extra whitespace where appropriate, particularly after a {, and deletes it when appropriate, particularly when you type a }. With both options turned on, you almost never have to press the tab key, saving a lot of time.</li>
</ul>

<p><span style="color: red">Note:</span> When pasting text into vim using the middle mouse button under X, autoindent and cindent can easily mess up the formatting of the text being pasted. You should turn both options off before pasting.</p>

<h3>Folds</h3>

<p>Many of the editors supplied with integrated development environments (IDEs) allow you to collapse large sections of code, such as a class, function, or loop body. Folds achieve the same effect in vim.</p>

<p>In C-like languages, a convenient way to fold all {} blocks is to do:</p>

<pre>:syn region myFold start=&quot;{&quot; end=&quot;}&quot; transparent fold<br />:syn sync fromstart<br />:set foldmethod=syntax<br /></pre>

<p>This will automatically fold all {} blocks. To expand the fold under the cursor, press <strong>za</strong>, and the same to close it again. To manually create a fold, use the <strong>zf</strong> command with a movement or Visual mode selection.</p>