Introduction to Vim
What Vim is, why it is on nearly every server you will log in to, how modal editing works, how to get out of it, and a first five-minute session.
By The Dark DebuggerUpdated 17 min read
This is the first article in the Vim path. It explains what Vim is and why it is worth your time, shows modal editing with real before-and-after files, covers every way to quit (and why people get stuck), and walks you through a first five-minute session. You only need a terminal and basic shell skills; if cd and cat are new to you, read Introduction to Bash first.
Why Vim is worth learning
Picture this: you SSH into a production box to fix a single wrong port in a config file. There is no VS Code, no desktop, no mouse. What you can count on is vi. On the Ubuntu 24.04 machine I used for every example in this path, vi is not the 1976 original at all. It is a symlink to full Vim:
readlink -f "$(command -v vi)"
vi --version | head -n 1/usr/bin/vim.basic
VIM - Vi IMproved 9.1 (2024 Jan 02, compiled Aug 24 2026 22:13:04)Vim also turns up when you did not ask for it. git commit without -m, crontab -e, visudo, kubectl edit and systemctl edit all open an editor, and on many systems that editor is vi. On Ubuntu specifically, Git falls back to the system-wide editor command, which is nano out of the box:
git var GIT_EDITOReditorSo you will not always land in Vim, but you will land in it often enough that "I don't know how to get out" is a real cost. Installing Vim and Learning with vimtutor shows how to make Vim the editor all of these tools use.
The second reason is the bigger one: Vim treats editing as a language. Keys are verbs (d delete, c change, y copy) and nouns (w word, $ end of line, i" inside quotes), and you combine them. Here is one line of Python and a single command, ci", typed with the cursor anywhere on the line before the string:
send_email(user.email, "Order shipped", render(event, "plain"), retries=3)After typing ci", then Order delivered, then Esc:
send_email(user.email, "Order delivered", render(event, "plain"), retries=3)"Change inside quotes". No selecting with the mouse, no counting characters. Once you know a dozen verbs and a couple of dozen nouns, you have hundreds of precise edits, and they work the same in Python, YAML, HTML or a commit message. Operators, Motions, and Text Objects teaches that grammar properly.
Modal editing, concretely
Most editors have one mode: every key you press types a character. Vim has several. The two you need on day one:
- Normal mode is where Vim starts. Keys are commands.
xdeletes a character,dddeletes a line,uundoes. - Insert mode is for typing. You enter it with
i(and a few other keys) and leave it withEsc. While you are in it, Vim says so at the bottom of the screen:
~
~
~
~
~
~
-- INSERT -- 0,1 AllThat -- INSERT -- line is the single most useful thing on the screen for a beginner. If it is there, keys type text. If it is not, keys are commands.
To see why this matters, I opened a one-line file and typed hello world without pressing i first. The file before:
Deploy checklistAnd after typing hello world in Normal mode, then pressing Esc and saving:
Deploy checklist
worldNothing called "hello" was typed. h moved left, e jumped to the end of the word, l l moved right, and o opened a new line below and switched to Insert mode. From there, world was typed as text. Every letter you type in Normal mode is a command, and some of them change your file.
Vim has more modes than these two (Visual for selecting, Command-line for : commands, Replace for overtyping). Modes and Moving Around covers all of them. For now, two rules carry you a long way:
- Press
Escwhen in doubt. It always brings you back to Normal mode. - Press
uto undo whatever just happened.
vi, Vim, and Neovim
You will see three names, and they are related:
| vi | Vim | Neovim | |
|---|---|---|---|
| Origin | Bill Joy, 1976, for BSD Unix | Bram Moolenaar, first released 1991, "Vi IMproved" | Community fork of Vim, started 2014 |
| Command | vi | vim (often also vi) | nvim |
| Config file | ~/.exrc | ~/.vimrc | ~/.config/nvim/init.vim or init.lua |
| Undo | one level | unlimited, with an undo tree | unlimited |
| Scripting | none | Vimscript and Vim9 script | Vimscript and Lua |
Bram Moolenaar maintained Vim for over thirty years until his death in 2023; Vim 9.1, the version used throughout this path, was dedicated to him and is maintained by the community. Neovim keeps Vim's editing model but modernizes the internals and plugin API.
For learning, the differences barely matter. Everything in this path (modes, motions, operators, text objects, search and replace) is the same keystroke for keystroke in Vim and Neovim. I tested every example with Vim 9.1; when a default differs between them, the article says so.
How to exit Vim (and why people get stuck)
"How do I exit Vim?" is one of the most viewed programming questions on the internet. People get stuck for four concrete reasons. I reproduced each one.
1. You are still in Insert mode. Typing :wq while -- INSERT -- is showing just inserts the text :wq and a line break into your file:
Deploy checklist:wq
- tag the release
~
~
-- INSERT -- 2,1 AllFix: press Esc first, then type :wq and Enter.
2. You changed something and tried :q. Vim refuses to throw away unsaved work:
eploy checklist
- tag the release
~
~
~
E37: No write since last change (add ! to override) 1,1 All(I had pressed x once, which deleted the D.) Either save with :wq, or discard with :q!. The ! means "yes, I really mean it".
3. You pressed Ctrl-C. In most terminal programs Ctrl-C quits. In Vim it does not; it prints a hint instead. With no changes:
Type :qa and press <Enter> to exit Vim 1,1 AllAnd with unsaved changes:
Type :qa! and press <Enter> to abandon all changes and exit Vim 1,1 All4. You pressed Ctrl-Z. That does not quit either. The shell suspends Vim and gives you a prompt back, which looks like Vim is gone:
$ vim checklist.txt
[1]+ Stopped vim checklist.txt
$Vim is still running, with your unsaved changes. Type fg to bring it back, then quit properly. If you forget about it and close the terminal, you will meet the swap-file warning described under Common mistakes below.
Here is every exit you need. All of them are typed in Normal mode:
| Keys | What it does |
|---|---|
:q | Quit. Refuses if there are unsaved changes (E37). |
:q! | Quit and throw away unsaved changes. |
:w | Write (save) and stay in Vim. |
:wq | Write and quit, always writing the file. |
:x | Write only if something changed, then quit. |
ZZ | Same as :x, no colon needed. |
ZQ | Same as :q!. |
:qa / :qa! | Quit all open files / quit all and discard changes. |
:cq | Quit with an error exit code. Tells programs like Git to abort. |
When I tested ZZ and ZQ: A (v2.4.0) then ZZ saved Deploy checklist (v2.4.0) to disk, while dd then ZQ left the file untouched.
A first five-minute session
Let's write a real file: notes for a web server. Every screen below is what Vim 9.1 showed me in an 80-column terminal.
Step 1: open a new file.
vim server-notes.md
~
~
~
~
~
~
"server-notes.md" [New] 0,0-1 AllThe ~ lines mean "past the end of the file". [New] says the file does not exist yet; Vim creates it when you save.
Step 2: insert text. Press i, then type these four lines (press Enter at the end of each). The typo in "ngnix" is deliberate:
# web-01 notes
- ngnix config: /etc/nginx/sites-enabled/app.conf
- reload after edits: sudo systemctl reload nginxStep 3: go back to Normal mode and save. Press Esc, type :w and press Enter. The bottom line confirms the write:
"server-notes.md" [New] 4L, 116B written 4,49 All4L, 116B means 4 lines and 116 bytes. 4,49 on the right is the cursor position: line 4, column 49.
Step 4: fix the typo. Type /ngnix and press Enter (that is a search; Search and Replace covers it). The cursor jumps to the n at line 3, column 3. Press l twice to stand on the second n, then type xp: x cuts the character under the cursor and p puts it back one position to the right. The line now reads:
- nginx config: /etc/nginx/sites-enabled/app.confStep 5: add a line, delete it, get it back. Press G to jump to the last line, then o to open a new line below it and type - error log: /var/log/nginx/error.log, then Esc. Now press dd and the line you just added disappears. Press u and it comes back; the bottom line reports what the undo did:
# web-01 notes
- nginx config: /etc/nginx/sites-enabled/app.conf
- reload after edits: sudo systemctl reload nginx
- error log: /var/log/nginx/error.log
~
~
1 more line; before #2 2 seconds ago 5,1 AllStep 6: save and quit with :wq. Back in the shell:
cat server-notes.md# web-01 notes
- nginx config: /etc/nginx/sites-enabled/app.conf
- reload after edits: sudo systemctl reload nginx
- error log: /var/log/nginx/error.logThat is the whole loop: Normal mode to move and command, Insert mode to type, Esc between them, :w to save. Everything else in this path makes those steps faster and more precise.
What this path covers
| # | Article | What you get |
|---|---|---|
| 1 | Introduction to Vim (this page) | Modes, exiting, a first session |
| 2 | Installing Vim and Learning with vimtutor | The right build, Vim as your default editor, vimtutor, a starter vimrc |
| 3 | Modes and Moving Around | Every mode, word/line/file motions, marks, the jump list |
| 4 | Editing Text: Insert, Delete, Change, Undo | The core edits, undo/redo, the dot command, saving variants |
| 5 | Operators, Motions, and Text Objects | The editing grammar: d, c, y plus motions and objects like i" |
| 6 | Search and Replace | /, *, :s, regex, :vimgrep across files |
| 7 | Visual Mode | Character, line and block selections |
| 8 | Buffers, Windows, and Tabs | Many files in one session |
| 9 | Ex Commands, Ranges, and :global | Line ranges and batch edits |
| 10 | Macros and Registers | Recording and replaying edits |
| 11 | Configuring Vim: vimrc, Mappings, and Plugins | Your own setup |
| 12 | Real-World Vim Workflows | Putting it together on real tasks |
Where you'll use this
The most common place people meet Vim without choosing it is the Git commit message. Here is a complete, real one. Git was configured with git config --global core.editor vim (the next article explains this), a file was staged, and I ran:
git commitGit opened Vim on a file called COMMIT_EDITMSG, with the cursor on an empty first line:
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch main
#
# Initial commit
#
# Changes to be committed:
# new file: app.conf
#
~
~
~
~
"~/webapp/.git/COMMIT_EDITMSG" 11L, 228B 1,0-1 AllI pressed i, typed a subject line, pressed Enter twice, typed a body line, then Esc and :wq. As soon as Vim exited, Git finished the commit:
[main (root-commit) e79269b] Add nginx server block for app.example.com
1 file changed, 4 insertions(+)
create mode 100644 app.confgit log -1commit e79269b7ae22c4a2499ac386237278b351855f93
Author: Sid <sid@example.com>
Date: Mon Nov 9 10:15:00 2026 +0000
Add nginx server block for app.example.com
Listens on port 80 only for now; TLS comes in a follow-up.The lines starting with # were dropped automatically. If you change your mind halfway through a commit, quit with :cq instead of :q!. Vim exits with an error code, and Git aborts instead of committing whatever was in the buffer (Exercise 4 shows the output).
The same skills apply to crontab -e (edit scheduled jobs), sudo visudo (edit sudo rules with a syntax check before saving), kubectl edit deployment/api (edit a live Kubernetes object), and systemctl edit nginx (create a service override). All of them hand you a temporary file in your editor and act on it when the editor exits, so knowing how to save, discard and abort is exactly what you need.
Common mistakes
Typing a sentence in Normal mode. This one does real damage. I opened a two-line checklist and, forgetting to press i, typed Run the smoke tests. The capital R switched Vim into Replace mode, and the rest of the sentence overwrote the first line:
un the smoke tests
- tag the release
~
~
~
-- REPLACE -- 1,19 AllThe fix is Esc and then u. One undo restored the line, and the message line said what happened:
Deploy checklist
- tag the release
~
~
~
1 change; before #1 1 second ago 1,1 AllUndo is cheap and unlimited in Vim, so when the screen surprises you, press Esc, then u until it looks right again.
The swap file warning (E325). Vim keeps unsaved changes in a hidden swap file (.checklist.txt.swp for checklist.txt). If the same file is already open in another terminal, or a previous session crashed or was killed, opening it again shows this. I left one Vim running on checklist.txt in another terminal and opened the file a second time (one line with the machine's host name is trimmed):
E325: ATTENTION
Found a swap file by the name ".checklist.txt.swp"
owned by: sid dated: Tue Nov 10 01:18:36 2026
file name: ~sid/notes/checklist.txt
modified: no
[…]
process ID: 631 (STILL RUNNING)
While opening file "checklist.txt"
dated: Mon Nov 09 22:04:34 2026
(1) Another program may be editing the same file. If this is the case,
be careful not to end up with two different instances of the same
file when making changes. Quit, or continue with caution.
(2) An edit session for this file crashed.
If this is the case, use ":recover" or "vim -r checklist.txt"
to recover the changes (see ":help recovery").
If you did this already, delete the swap file ".checklist.txt.swp"
to avoid this message.
Swap file ".checklist.txt.swp" already exists!
[O]pen Read-Only, (E)dit anyway, (R)ecover, (Q)uit, (A)bort:Read the process ID line. (STILL RUNNING) means another Vim really has the file open, often one you suspended with Ctrl-Z or left in a different tmux pane. Press q and go find it. If the process is not running, the earlier session died: press r to recover its unsaved changes, save, and then delete the .swp file.
Losing a suspended Vim. After Ctrl-Z, the shell prints [1]+ Stopped vim checklist.txt and gives you a prompt. Run jobs to see suspended programs and fg to resume the most recent one. Closing the terminal instead leaves your edits only in the swap file.
Summary
- Vim is on nearly every Linux server; on Ubuntu,
viis a link to full Vim (/usr/bin/vim.basic). Git, cron, visudo and kubectl all drop you into an editor that is often Vim. - Normal mode is for commands, Insert mode for typing.
-- INSERT --at the bottom tells you which one you are in, andEscalways gets you back to Normal mode. - Letters typed in Normal mode are commands:
oopens a line,Rstarts overwriting text.uundoes, as many times as you need. - Exits:
:wqor:x/ZZsave and quit,:q!/ZQdiscard,:cqmakes the calling program (such asgit commit) abort. - E37 means unsaved changes. Ctrl-C only prints a hint. Ctrl-Z suspends Vim;
fgbrings it back. - E325 means a swap file exists. Check whether the process is still running before you choose Quit, Recover or Edit anyway.
Exercises
Create todo.txt containing these three lines, save it, quit, and confirm the contents from the shell:
- renew TLS certificate
- rotate API keys
- update runbookShow Solution
vim todo.txtPress i, type the three lines (press Enter between them), press Esc, then type :wq and Enter.
cat todo.txt- renew TLS certificate
- rotate API keys
- update runbookOpen todo.txt, delete the first line twice with dd dd, undo once with u, then try :q. Read the message, quit without saving, and prove the file on disk did not change.
Hint
Save a copy first (cp todo.txt todo.orig) so you have something to compare against.
Show Solution
After dd dd u one deletion is still applied, so :q refuses:
- rotate API keys
- update runbook
~
~
~
E37: No write since last change (add ! to override) 1,1 AllType :q! and Enter to discard. Then:
cmp todo.txt todo.orig && echo "unchanged"unchangedcmp prints nothing and succeeds when two files are byte-for-byte identical.
Recreate the checklist from Common mistakes, then make the mistake on purpose and recover from it without retyping anything:
printf 'Deploy checklist\n- tag the release\n' > checklist.txt
cp checklist.txt checklist.orig
vim checklist.txtIn Normal mode, type Run the smoke tests. Get the file back to its original state, save, and verify.
Show Solution
Press Esc (you are in Replace mode after the R), then u, then :wq.
cat checklist.txt; cmp checklist.txt checklist.orig && echo "identical"Deploy checklist
- tag the release
identicalThe whole overwrite counts as a single change, so one u restores it.
In a scratch Git repository, stage a file and run git commit (with Vim as Git's editor: git config --global core.editor vim). Type a message, then make Git abort the commit from inside Vim. Confirm that nothing was committed.
Show Solution
mkdir repo && cd repo && git init -q -b main .
printf 'listen 443 ssl;\n' > tls.conf && git add tls.conf
git commitIn Vim, type iWIP, press Esc, then :cq and Enter. Git reports:
hint: Waiting for your editor to close the file... error: There was a problem with the editor 'vim'.
Please supply the message using either -m or -F option.git status --short
git log --onelineA tls.conf
fatal: your current branch 'main' does not have any commits yetThe file is still staged (A) but no commit exists. :q! would not have been enough here: the message file already had WIP in it, and quitting normally would let Git commit it.
Tested with: Vim 9.1.0016 (Ubuntu package 2:9.1.0016-1ubuntu7.20) and Git 2.43.0 on Ubuntu 24.04 (WSL2), November 2026.
Every screen in this article was captured from a real Vim session running in an 80- or 100-column terminal, driven by the exact keystrokes described. Commit dates were pinned with GIT_AUTHOR_DATE so the hashes are reproducible. Neovim was not installed, so the Neovim notes come from its documentation, not a test run.
Written by The Dark Debugger
Engineer documenting the things that took me too long to learn, so they take you less time. Every Vim tutorial here is tested end to end before publishing.