VI Editor: Usage Guide
When you edit a file over SSH — a server config, a cron job, a Dockerfile on a remote box — there is no
IDE. There is only the terminal, and the editor installed on almost every Unix system is
vi (or its enhanced version, vim). This guide covers the mental model you need
— the modes — and then the practical commands: opening, saving, searching, replacing with regex, deleting
ranges, and copying text between files. I also list the errors beginners hit most, starting with the one
everyone has seen: "E37: No write since last change".
The Core Foundation: Modes
The single most important thing to understand about Vim is that it is modal. Unlike a normal editor, typing letters does not insert text — it depends on which mode you are in:
- Normal mode (default on start): keystrokes are commands — navigate, delete, copy.
- Insert mode: typing inserts text, like a normal editor.
- Visual mode: select text with the cursor to yank (copy), delete or replace a block.
- Command-line mode:
:-prefixed commands such as:w,:qor:%s/.../....
Press i to enter Insert mode, Esc to return to Normal mode. This one habit —
reach for Esc after every edit — solves most beginner confusion.
1. Opening, Saving and Quitting
Open a file (create it if it does not exist):
vi filename.txt
The essential save/quit commands, in Normal mode:
i— enter Insert mode to start typingEscthen:w— save (write) the fileEscthen:q— quitEscthen:wq(or:x) — save and quitEscthen:q!— quit without saving (discard changes)
If you try to quit with unsaved changes, Vim refuses: E37: No write since last change. That
is the guard against losing your work — use :wq to save, or :q! to deliberately
discard.
2. Moving Around
hjkl— left, down, up, rightw— jump forward one word,b— back one word0— start of line,$— end of linegg— top of file,G— bottom of file:42— jump to line 42
3. Searching Inside a File
In Normal mode, press /, type the text, and press Enter. Vim jumps to the first match
forward from the cursor:
/search_text
n— jump to the next matchN— jump to the previous match?search_text— search backwards:noh— remove the search highlight
4. Global Search and Replace with Regex
To replace every occurrence of a string across the whole file, use the substitute command:
:%s/old_text/new_text/g
Breaking it down:
%— the range: the entire file. Use1,5for lines 1–5 only, or nothing for the current line.s— the substitute commandg— replace every match on each line, not just the first one
To see each match and confirm before replacing, add the c flag:
:%s/old/new/gc. This is a safe way to rename a variable across a config file you cannot
afford to break.
5. Escaping Special Characters in Searches
Search patterns are regular expressions, so characters like /, . and
" have special meaning. Escape them with a backslash to match the literal character. You can
also join several alternatives with \|:
/\@gmail\|\/opt\/logs\|"4
This pattern matches any line containing @gmail, the path /opt/logs, or the
literal string "4. I used exactly this search while scanning logs and config files for
several patterns at once.
6. Deleting Lines and Ranges
dd— delete the current line5dd— delete five lines from the cursor:1,5d— delete lines 1 through 5:.,$d— delete from the current line to the end of the filedw— delete one word
7. Copy Text Between Files with Visual Mode
To move a block of text into another file:
- Move the cursor to the start of the block and press
v(orVfor whole lines). - Move the cursor to select the range you want.
- Press
yto yank (copy) it into memory. - Quit to the shell with
:wq, then open the target file:vi newfile.txt - Press
pto paste below the cursor line (orPabove it), then save with:wq.
Visual mode is also the fastest way to delete a precise column of text: press Ctrl+v for
block selection, move over the columns, then press x or d.
Verifying Changes
After :wq, confirm the file content from the shell:
cat filename.txt
Common Problems
Problem 1: "E37: No write since last change" (can't quit)
Cause: you edited the file and Vim refuses to exit without saving.
Solution: :wq to save and quit, or :q! to discard all
changes.
Problem 2: typing letters does nothing / text appears in the middle of commands
Cause: you are in the wrong mode. In Normal mode letters are commands; in Insert mode they are text.
Solution: press Esc to return to Normal mode, then use
:w, :q, etc.
Problem 3: "E212: Can't open file for writing"
Cause: you do not have write permission for the file (e.g. /etc/ files).
Solution: re-open with sudo: sudo vi /etc/nginx/nginx.conf. If you already
made changes, write with :w !sudo tee % — but the cleaner habit is to start with sudo.
Problem 4: arrows/backspace behave oddly
Cause: insert mode is in strict vi compatibility and the terminal is sending escape sequences Vim reads as commands.
Solution: run vim (not plain vi) and add to
~/.vimrc:
set nocompatible
set backspace=indent,eol,start
Best Practices
- Always press
Escbefore you think. "Esc, then command" is the safest sequence. - Use
:%s/old/new/gcfor anything you cannot afford to break — confirmation is free. - Keep a
~/.vimrcwith at leastsyntax onandset number. - For system files, always edit with
sudofrom the start.
Conclusion
Vim's learning curve is the mode system: once you accept that letters are commands until you press
i, everything else follows. Master the save/quit commands (:wq,
:q!), search (/text), and replace (:%s/old/new/g), and you can
confidently edit any file on any server.