Captain's Log Supplemental

Welcome to an introduction and usage study of one of the worlds most common text editors. It is also my favorite style of editor. We cover several sections each detailing a given aspect of the Vi editor.

Table of Contents

Short history
Which Vi is my Vi ?
Initial Fear
Learning Vi
      Required Commands
      Helpful Functions
      A few extra commands
      Making sense of Vi options
      Deletion Wars
      Cut, Copy, and Paste the Vi style !
Options and configuration
How to make a exrc file

Document Version: 0.90.0

This post has the underlying assumption that you want to learn to use the Vi text editor but know jack about it. I won’t insult you but I’ll try to teach it without being to terse or “hand holding”. We all need help but one has to put in a little bit of effort to master a program.

I have always cared more for content and understandable English then for closely following the “laws of the English anguage” so forgive any grammatical errors and ether curse or help improve the content 😛

Short History
In 1976 a man named Bill Joy wrote the Vi text editor for an early BSD release. It took the existing ed and ex line editors and created a visual interface. While ex was a simple line editor vi gave us an interface much more like what we are accustomed to in this era.

Vi is a modal text editor which means that depending on what editing mode one is in at any given time what each key does changes. Vi has thankfully only two editing modes of importance command and insert. Unlike common editors such as Emacs or Kate commands are entered by shifting the entire keyboard into command mode and back into insert mode to continue inserting text. This modal concept is probably the biggest adjustment new users have to make when learning Vi. Some notable influences on the Vi command set was the ADM3A terminal which had the Esc and left Control keys where the Tab and Capslock keys are on modern US_QWERTY keyboards. There was also arrows on the H, J, K, and L keys which intern became the Vi movement keys.

Picture of ADM3A Keyboard

Which Vi is my Vi ?
There have been many vi implementations and clones through the years and on many systems but you can always count on an Unix to have a Vi. By high decree of the POSIX (Portable Operating System Interface for uniX). It would be best that before you try to start learning how to use Vi you learn what type of Vi editor you have. Many GNU/Linux systems will use a Vi clone in place of Vi while BSD Unix’s use nvi. This how to should be relivent to every Vi/Vi Clone but most Vi Clones have a lot more to offer then Vi does.

Vi is the classic BSD
implementation now free and open source under a BSD style license.

Nvi is a re-implementation of Vi used for the 4BSD release when the original Vi was considered encumbered code. This is what is like wise used on Free, Net, Open, PC, and Desktop BSD and the focus of this how to.

Elvis is a Vi clone that adds a number of features and commands. Elvis functions on Unix, Dos, NT, and OS/2 systems both as a console and graphical application. It is standard issue on Slackware Linux for the systems vi program.

Vim or Vi IMproved is a Vi clone that implements many additional features and options. It’s known to run on many platforms including Amiga, GNU/Linux, Mac OS X, Windows, OpenVMS, OS/2, and Unix like systems. Vim supports several graphical user interfaces including Motif, GTK1, GTK2, and Athena versions. It is also what this post was written with.

Vile was initially derived from an early version of Microemacs in an attempt to bring the “modern” benefits of the Emacs multi-window/multi-buffer editing paradigm to users more comfortable with the vi command-set. Vile functions on DOS, Windows, OS/2, GNU/Linux, Mac OS X, and Unix like systems.

Viper-mode of the popular Emacs editor tries to emulate many common vi commands and may prove interesting to emacs users and humorous.

It does not matter what Editor one uses as long as one is happy, productive, and effective but I would recommend using a Vi Clone with good documentation. So know any good jokes about Vims 25,000,000,000 page manual ? Hehehe.

You may invoke the vi editor from a console window by typing “vi”, if your using another type of editor or “vi clone” please consult it’s documentation.

Initial Fear
The traditional vi runs in a command window which is enough to scare off many new users. While newer Vi Clones such as Vim and Elvis have graphical user interfaces that can run with such luxurious features as tool bars and menus it is important to know that the editors are still available in the command line environments without loss of functionality.

One of the most confusing things to scare you about learning Vi is the concept of editing modes. Most users are used to an editor that starts with and is always in “insert-mode” that is you type on the keyboard it and writes text to the screen. Vi by default starts in a command mode where the keys are used to issue editing commands such as delete, replace, yank (copy), paste, cut and movement keys and such. When one wants to start writing text they have to enter insert mode. Once you get sed to this idea you will start to grasp Vi much better. When you are working in insert mode Vi will behave in a similar manor to what most users expect a few differences aside (like the Esc key and copy/paste commands). To indirectly quote a man named Jon Lasser about vi editing modes.

When you move your (mouse) pointer out of the screen area, you can’t type in text. You have, in effect, moved from insert mode to command mode. “It’s the same thing,”

Most implementations of Vi including nvi should be able to make use of ones cursor (arrow) keys and the insert/home/pgup/del/home/pgdwn clusters we take for granted but using the arrow keys are less effective then using command mode & the classic movement keys. I’d say you should try to use the cursor keys for simple movement at first because they work in any mode and are less foreign. When some day you find yourself without working cursor keys you will be bloody
happy you learned to use H,J,K,L instead of LEFT, UP, DOWN, RIGHT. Trust me it can happen, I once had a very bad system boot the kind your usually lucky to be able to fix without a rescue disk kind. I had to edit a file and my choices of editors were rather limited (ed, ex, vi, ee). When I ran vi it could not use my cursor keys forcing me to use the H,J,K,L cluster in it’s place. Never before was I so glad to know two ways of doing the same thing in a text editor !

Learning Vi

I will split this section into several groups of commands. When I first tried to learn Vi(m) I didn’t like it because I could not figure it out at the time. After a while on the FreeBSD command line I learned how to use it. In the process I also learned the easiest way to learn how to use Vi, aside from using Vim instead (:help) was to learn things in small pieces. It won’t do you any good to try and learn Vi all at once but if your able to just sit down and inhale it I’ll probably edit in a cheat sheet or a link to one at the end of this how-to.

Required Commands

So named because these are what I feel are the fewest commands one needs to know in order to use Vi. Maybe not use it well but use it as well as Notepad is a good editor. While we are on the subject of Notepad. Just to say it, notepad is a good editor for several reasons:

It is on nearly any Windows system, it’s very simple and light weight.

You don’t need a Ph.D to use it.

It’s also very week and very basic.

Vi like many Vi users prefer Speed, Power, and Efficiency over a small inertial learning curve. Many people say Vi is not intuitive to learn but I must disagree it is only a matter of adopting ones mind to shifting between insert and command modes. The more one learns with Vi the more productive they will be but no one need learn every thing on day one !

These are the core super simple commands you have to know to use Vi like most editors.

Key         Action

h           Move left one character - the left arrow does this as well
j           Move down one line - the down arrow does the same thing
k           Move up one line - the up arrow does this too!
l           Move right one character - Right arrow yet again.
Esc         Enter Command Mode /or cancel commands
i           Enter insert mode - the Insert key will also work
x           Delete the character under the cursor - just like the Delete key.
ZZ          Save file and quit Vi

To tell the truth compared to using Notepad you only learned 3 commands. Esc, i, and ZZ or enter command mode, enter insert mode, and write file and get me out of this crazy editor!

The h, j, k, l, and x keys are analogous to the arrow keys and the insert and delete keys on your keyboard. The only difference is these keys work when nothing else does. Some terminals don’t support luxuries well such as home and end keys so when working on a machine from a remote session or laptop these can be your best friends. You should be able to live with having to press ESC to use commands and go to insert mode to input text.

Helpful Commands

These are more keys and commands that are not necessary to edit a file but do make live a lot easier especially if you often find your self editing text not just creating it. If you have some experience with some thing called regular expressions a few of these might even seem familiar to you.

Key         Action

:           Enter "ex" like commands in a "command line" mode
:w          Write changes to file
:q          Quit Vi
:e file     Open file for editing

/word       Find "word" much like Control+F in many other editors
n           Go to next occurrence of the search term below the current
N           Go to next occurance of the search term above the current one

a           Enter insert mode right of the cursor
A           Enter insert mode at the end of line
o           Insert line below cursor
O           Insert line above cursor
w           Move forward one word
b           Retreat one word
$           Move cursor to the end of the line
^           Move the cursor to the start of the line
Control+u   Page up half a screen
Control+d   Page down half a screen

u           Undo previous command(s) - some Vi clones have unlimited undo/redo
Control+r   Redo the undone command(s) - same as above ^

r           Replace one char and return to command mode
R           Enter Replace mode - works like pressing insert in most editors
c           Change, takes an operator like d. example: cw=changes a word
d     Delete using a following movement command (see below)
dd          Delete entire line

None of these commands are necessary to know but they sorta make life easier. Personally I find these much easier on the wrists then Emacs which uses key combinations using the Control and Meta keys instead of a command mode.

A few words about the “:” key, it enters a little command line mode. When you press the : key in command mode it gives you a command line to type an ex (extended editor) type of command. After you have typed the command you press enter to run it and should return to normal mode. If you need to force a write or quit you can append the “!” Symbol to it. If you are a ex guru or need to enter many commands in this way you might try the “Q” command to enter Ex mode. For example the ZZ command is the same as :wg. One can mix and match actions and movements very well in Vi, for example if one wanted to delete to the end of the line you could use command mode to enter d$ and delete from the cursor to the end of the line. When one shifts between command and insert modes often in there editing style you soon find the a, A, r, o, and O keys very useful. I’ve mentioned a few other modes then command and insert but they are of little importance to you unless your into reading good ocumentation. Consult your Vi implementation for details, for users of nvi it’s nothing to fart about at this stage of learning. Many commands allow one to specify a location or a movement. This is especially true for using the commands for deletion, joining text, copy/cut/paste, and multiple editing buffers (windows) if your vi supports it.

You might want to get used to using most of these commands or at least the concepts be fore we try to tackle such tasks as more advanced delete or copy/paste commands. A coffee break about now is a very good idea.

A few extra commands

These are other commands useful to users but I broke them off from the above list to ease session based learning.

Key         Action

:!cmd       Execute shell command cmd.
:command!   Force command to run, such as force write-quit (:wq!)
:r!cmd      Run cmd in shell and insert it's output in the file

G           Go to end of buffer (the bottom of the file)
1G          Go to line one in the file
nG          Go to line n. So 10G means go to line 10

>>          Shiftwidth text over one indentation level to the right
<<          Shiftwidth text over one indentation level to the left

One cane execute commands from vi that one would usually run in a shell such as bash or cmd.exe. :!dir b “C:Program Files” would be executed just as if one ran the dir command from cmd.exe or command.com. If you want to nab the output of a command into your file use :r!command this is very good if one needs to quickly grab some data thats a fast pipe away. The G command is a go to without any arguments it goes to the bottom of the file. If one was to type a number before it it would go to that line number. The >> and << are useful for shifting text around but have likely little need for users not into programming or scripting e.t.c. So I have nothing to say about these commands. Making sense of Vi optionsOne of the worst things is that by default vi generally does not tell you what mode you are in or where the cursor is this can make life harder. Lucky for us Vi has the ability to set options. Really this belongs in a customizing vi section and I’ll probably paste it there but I think knowing some of this now will help you. You can set options thus turning them on, off, or setting a value :set option :set nooption :set option=10 If you want to see all the options available you can type :set all if you have a good Vi clone you should be able to get some documentation on what all of these do, for the sake of making Vi more friendly we will cover some good stuff here. :set showmode :set ruler ;set ignorecase These three options (in order of appearance) will make vi show you the current mode at the bottom of the screen, show you the cursors position as line,character at the bottom of the screen, and turn off case sensitivity when searching in a file. You can make a startup file that vi will read when it starts that will set options for you. Ex/Vi and Nex/Nvi use the /etc/exrc and ~/.exrc files but depending on your implementation it may be different such as Vim or Elvis. I don’t have much experience with Elvis but for Vim it reads the .vimrc file(s). You can turn these off pretty easy like so :set noshowmode :set noruler :set noignorecase If you want to make a .exrc file for your self you can store commands in it that are what you would type after hitting : so a .exrc file enabling showmode would look like this: set showmode and saved as ~/.exrc if you want to leave a comment in the file preside it with a single ” quote. The ” Comment marks that entire line after the ” character not to be read when starting up. A few options that may interest you are autoindent, tabstop, shiftwidth, wrapmargin, and warplen. By default when one tries to type past the end of the screen it rolls to the line below on screen but is treated as one long line. One can try and make this more like most editors word wrapping with some play time. I will only discuss the autoindent option since it is some thing you will ether long for or hate if you use vi for editing code, scripts, web sites e.t.c. When one sets autoindent on vi starts a new line with the same indentation as the last. The word indentation is a little odd in my opinion if your not a programmer so I’ll give a short example of how it goes.

if i is-greater-then 0
      do this code
      and this code
else
      do this instead
endif

If typing that with autoindent on pressing return after typing “do this code” would automatically indent the next line to the same level. You can press Control+D to kill the autoindent such as if you wanted to place the “else” in our pseudo code at the same level as the “if” and “endif”. Deletion WarsIf you remember awhile ago when we both were still sane. I mumbled about being able to combine a command and a movement. This is pretty much true with most movement, deletion, and “visual” commands (visual as in cut, copy, paste). x deletes the letter under the cursor but what if we want to delete some thing else? We can use the d key along with a movement specifier if you recall the movement keys h, j, k, l, $, ^ we can combine them all with d to make it mean delete this way. So d^ really means delete to-start-of-line. This makes for very versatile work and it’s not just limited to deletion. Much like we can use a number and G to go to a line like 275G to go to the 275th line of a file. Nvi users will especially need to know this for dealing with copy/paste as it lacks a Visual mode that makes it more like other editors. A very fast way to delete an entire line is the dd command or deadly delete 🙂 You can prefix a number of lines to a command as well, so for example 10dd will delete the current line and the next ten for you. Unlike most editors Vi does not really know you have a mouse, although Vi Clones should if they have a GUI. Some like Elvis and Vim have a “visual” mode that can highlight text using movement keys and then delete it or do the cut, copy, and paste antics with it.

Key         Action

y           Yank (copy) - selects text in a similar manner to the d command
yy          Yank line - selects text in a similar manner to the dd command
yyp         Duplicate line - copy/paste current line on the line below.
p           Put (paste) text
v           Enter visual mode - for some Vi Clones

One should really know both ways if possible. Personally I prefer visual mode, it’s more like what we are all used to. That is you select (aka highlight) text then do with it what you want, such as copy or delete. With classic Vi as included in FreeBSD at least one will get an error. If one wanted to copy the current line and the next tree. You would type 3y in command mode. Go to where you want to paste it and press p key in command mode. This is more or less how it works in traditional Vi. This is how it can also be done in a Vi clone like Vim. You can enter visual mode (v key). Once you do that the editor starts treating the cursor movements just like when you old the left mouse button and start dragging the pointer around. Only it works without a mouse ! Once you’ve high lighted some text you can act on it.So for example if you pressed “vwwd” you would have just deleted from the current cursor position to the next two words. You can use the “c” command to “cut” in visual mode. I have not tried elvis much but it should be similar to vim. Search and Replace If you are familiar with regular expressions, sed, awk, ed, or ex you should be at home right here. The search & replace takes syntax like this ‘n,m s/find expression/change expression/cmd’. So if I wanted to change every occurrence of ‘vi’ to ’emacs’ in this file I could do this. :1,$s/vi/emacs rules/g That is from line 1 to end of lines search for the string vi and replace it with emacs globally. If I only wanted to change it for n through m lines I could have tried some thing like this :260,285s/emacs/vi/g Regular expressions are similar to the wild cards used by the shell but they are different. Same concept (imho) but different syntax. Much like C and C++ maybe. A detailed Analise of regular expressions would be out side the scope of this how-to and totally irregular 🙂 I suggest the following links for more info about regex (regular expressions) http://en.wikipedia.org/wiki/Regex http://www.regular-expressions.info/ Back in the days before operating systems when software ran on the bare hardware. Stuff like this “regular expression” mumbo-jumbo was a thing just for the uber-nerdy scientist but now it’s in the power of your editor. It should also be worth learning how to use regex. As it is a common syntax with many uses. The better you know regular expressions the better you will be able to use tools like sed, grep, awk, find, perl, ex, and many more. Options and Configuration We touched on this back in section 4.4.Making Sense of Vi options but will go over a few things again. Saves your scroll bars eh? 🙂 Vi has a number of options that adjust the way it behaves, here is screen dump of the default setup of nvi. As used on FreeBSD 6.1-Release.

~
+=+=+=+=+=+=+=+
noaltwerase     noextended      matchtime=7     report=5        term="xterm"
noautoindent    filec=""        mesg            noruler         noterse
autoprint       flash           nomodeline      scroll=12       notildeop
noautowrite     nogtagsmode     noprint=""      nosearchincr    timeout
backup=""       hardtabs=0      nonumber        nosecure        nottywerase
nobeautify      noiclower       nooctal         shiftwidth=8    noverbose
cdpath=":"      noignorecase    open            noshowmatch     warn
cedit=""        keytime=6       optimize        noshowmode      window=24
columns=85      noleftright     path=""         sidescroll=16   nowindowname
nocomment       lines=25        print=""        noslowopen      wraplen=0
noedcompatible  nolisp          prompt          nosourceany     wrapmargin=0
escapetime=6    nolist          noreadonly      tabstop=8       wrapscan
noerrorbells    lock            noredraw        taglength=0     nowriteany
noexrc          magic           remap           tags="tags"
directory="/tmp/"
msgcat="/usr/share/vi/catalog/"
paragraphs="IPLPPPQPP LIpplpipbp"
recdir="/var/tmp/vi.recover"
sections="NHSHH HUnhsh"
shell="/usr/local/bin/ksh93"
shellmeta="~{[*?$`'""
Press any key to continue [: to enter more ex commands]:

You can get a screen like this by using the :set all command. Every option or “variable” can be turned off by appending ‘no’ to the command. So if we wanted to turn on autoindent we would :set autoindent We could also have used the short form and typed :set ai but that makes it harder to read. Why this matters I’ll tell you in a sec 😛 To turn it off we would then type this. :set noautoindent Some options take a numeric value and are set like this :set shiftwidth=4 I’ll try to quickly document each of these options the best I can ones of value. So you can choose what you prefer. I’d suggest if you want to modify Vi’s behavior to test a few options to see how you like the changes. If I have no information about the option, it is not listed. Option: autoindent Short form: ai Value: on/off Default: noautoindent Description: When turned on ‘ai’ will automatically start the new line to at the same depth as the previous line when breaking lines (i.e. pressing enter). The value of the ‘shiftwidth’ variable is used when inserting tabs. When your done you can undo the autoindent by pressed the control+d. I’ve yet to figure out if it is a bug or a configuration error but if tabstop and shiftwidth have different values. Control+d will not un-indent the line correctly if sw and ts are not equal. Line one line two Autoindented Cntrl+D Option: autoprint Short Form: ap Value: on/off Default: noautoprint Description: I don’t see any effects but my reference says ‘Display changes after each command.’ Option: autowrite Short Form: aw Value: on/off Default: off Description: Automatically write changes to file after certain events. Option beautify Short Form: bf Value: on/off Default: off Description: Ignore all control characters during input (except tab, newline, formfeed). Pressing control+letter in insert mode when no command exists will result in text like this by default. How to delete a tpyo�� No I’m not trying to insult emacs users, I would probably use M-B M-D to fix such a typo when using Evil Macs. Option: columns Shot Form: col Value: numeric Default: varies Description: The number of columns to use for the text area. Example, how to set vi to 85 columns wide. :set columns=85 Option: edcompatible Short Form: ed Value: on/off Default: off Description: Use ed-like features on substitute, probably more useful for Bill Joy then you or me. Option: errorbells Short Form: eb Value: on/off Default: on Description: Sound the system bell when you make a booboo. Option: exrc Short Form: ex Value: on/of Default: off Description: Vi can read an exrc file that will run a set of commands at startup. Basically a configuration file for setting your options (see next chapter). Option: hardtabs= Short Form: ht= Value: numeric Default: 8 Description: Set boundary for hardware tabs, may be useful for a Teletype. Option: ignorecase Short Form: ic Value: on/off Default: off Description: Ignore case in regex expressions. Option: lisp Short Form: ? Value: on/off Default: off Description: Turn on lisp mode, I think it aids the formating of old lisp code. Option: list Short Form: ? Value: on/off Default: off Description: Display all tabs, end of lines. Turn this on for fun 🙂 Option: magic Short Form: ? Value: on/off Default: on Description: Enable more regex expressions Option: mesg Short Form: ? Value: on/off Default: on Description: Allows mesgs to be sent to terminal, see man mesg(1) Option: number Short Form: nu Value: on/off Default: off Description: Enables line numbering, this can help when debugging files. I usually have a mapping to enable it with the F2 key in my ~/.exrc file. Option: prompt Short Form: ? Value: on/off Default: on Description: Enalbes the ‘:’ prompt, if you disable this you can make ex behave more like ed. You probably don’t want this. Option: readonly Short Form: ro Value: on/off Default: off Description: Prevents you from writing the file unless you override it like so. :w! Option: redraw Short Form: ? Value: on/off Default: off Description: Redraw screen when edits are made, probably works like the Control+L command (refreshes screen). Option: report= Short Form: ? Value: numeric Default: =5 Description: Report changes if they effect more lines then report=n. Such as when using the delete/yank/join commands e.t.c. Option: shiftwidth= Short Form: sw= Value: numeric Default: 8 Description: How many characters to use when shifting width with the >> and << commands e.t.c. If you plan to use autoindent, the value of sw and ts should be the same (see below). Option: showmatch Short Form: sm Value: on/off Default: off Description: The cursor will flash and move to the openning {, }, (, ), [, or ] when typing a closing one on screen. Option: showmode Short Form: ? Value: on/off Default: off Description: Shows which mode you are in such as command, insert, append, or replace. This is so useful its a perfect choice for the beginners exrc file. Option: tabstop= Short Form: ts= Value: numeric Default: 8 Description: How many characters to display a 'tab' as, mostly of use for programmers. Common choices are 2, 4, 6, 8, 10, 12. It has been suggested that one should not change this setting but instead adjust the shiftwidth setting. I can only say from personal experience if you change tabstop but forget to change shiftwidth to the same. Auto-indent will be a bit off :-) Option: wrapmargin= Short Form: wm= Value: numeric Default: 0 Description: Set the right margin. Setting a value greater than 0 will word wrap n spaces from the edge of the screen. So :set wm=5 would make the display wrap lines when ever it hit the 5th to last line of the terminal. Option: wrapscan Short Form: ws Value: on/off Default: on Description: Searches wrap around end of file How to make a exrc fileThe exrc file is very simple. Commands are read from the ~/.exrc file just as they are from the ‘:’ command line in Vi. Placing this line in your exrc file set autoindent Is the same as tying :set autoindent in command mode. You can use the double qoute or ” character to comment a line. ” This line is not read by Vi set tabstop=6 Here is an example of what my ~/.exrc file might look like with extra comments.

" Tell me what mode I'm in between coffee breaks
set showmode
" Press F2 to turn on line numbering, make the ^M with ctrl+v ctrl+m
map  :set number
" Alias ';' to :
map ; :

UNDER CONSTRUCTION

__            ___      ___  
|  |         /  /    /  /     
|  ||        /  / /   /__/ /   
|  ||       /  / /    __/    
|  ||      /  / /   ___    
|  ||     /  / /   /  /    
|  ||    /  / /   /  / /    
|  ||   /  / /   /  / / 
|  ||  /  / /   /  / /  
|  || /  / /   /  / /
|  ||/  / /   /  / / 
|  |/  / /   /  / /  
|     / /   /  / /   
|    / /   /  / /    
|   / /   /  / /   
|__/ /   /__/ / 
__/    __/