Editing Files with vi: Modes, Safe Saves, and Essential Commands

The first time you open vi, pressing a letter may move the cursor instead of adding text. That’s not a broken keyboard: vi is a modal editor, and its keys do different things depending on which mode you’re in.

Once you know how to switch modes—and how to save or discard changes—vi is much less intimidating. It’s also useful when you need to edit a file from a terminal, including on a remote server.

The basic edit-and-save loop

Open a file by passing its name to vi:

vi notes.txt

If the file exists, it opens for editing. If it doesn’t, vi creates a new buffer; the file is created when you save it. You can also give a path, such as vi /etc/example.conf. Make sure you’re in the intended directory, and remember that protected files require appropriate write permissions.

When vi opens, it starts in command mode. To type text, press i to enter insert mode. When you’re finished, press Esc to return to command mode. Then type :wq and press Enter to write the file and quit.

The whole sequence is:

1. Run vi notes.txt.
2. Press i and type your text.
3. Press Esc.
4. Type :wq and press Enter.

Colon commands appear along the bottom of the terminal. If :wq ends up in your file as text, you were still in insert mode—press Esc and try again.

If you’re creating a file rather than editing an existing one, there are also shell commands for that; this guide to creating files in Linux explains a few options and what they do.

Modes: the one idea that explains most confusion

In command mode, keys control the editor: they move the cursor, search, or change text. In insert mode, typed characters become part of the file.

• Press i to insert before the cursor.
• Press a to append after the cursor.
• Press o to open a new line below the current one and begin inserting.
• Press Esc to return to command mode.

If you’re unsure which mode you’re in, press Esc once or twice. Then choose your next action: press i to type, or enter a colon command to save or quit.

Save, quit, or throw away changes

Press Esc before entering one of these commands, then press Enter:

Command	What it does
:w	Save changes and stay in the editor.
:wq	Save changes and quit.
:x	Save if needed and quit.
:q	Quit if there are no unsaved changes.
:q!	Quit without saving changes made since the last write.

A plain :q won’t silently discard your work; if changes are unsaved, vi refuses to quit. Use :q! only when you really intend to abandon those edits. The ! overrides the warning—it does not save anything.

A small set of useful editing keys

These commands work in command mode, so press Esc first if you’ve been typing:

• h, j, k, l: move left, down, up, and right.
• 0: move to the start of the current line; $: move to its end.
• x: delete the character under the cursor.
• dd: delete the current line.
• yy: copy (yank) the current line; p puts copied or deleted text after the cursor, or below the line for a linewise copy.
• u: undo the most recent change.

To search forward, type /server_name and press Enter. Press n to move to the next match.

For a simple replacement, use :s/old/new/ to replace the first match on the current line. Add g to replace every match on that line. To replace matches throughout the file, use:

:%s/old/new/g

Review replacements before saving, especially in configuration files. Features and options can differ between vi implementations.

Editing a file on a server

When you run vi over SSH, the editor runs on the remote machine. Save your changes before closing the connection. If you’re new to connecting from a terminal, this OpenSSH command walkthrough covers the basic connection syntax and commonly used options.

Be careful when editing system configuration: a typo can affect a service or prevent it from starting correctly. Check your changes before saving, and avoid elevated privileges unless you need them. If saving fails with a permission error, don’t quit if you still need the unsaved text. Reopen the file with the appropriate permissions when necessary.

Quick recovery when you get stuck

• I can’t type: press i or a to enter insert mode.
• My command went into the file: press Esc, then enter it again.
• I need to save but keep editing: use :w.
• I need to exit and keep my edits: use :wq.
• I need to exit without keeping unsaved edits: use :q!.

The key habit is simple: press Esc to get back to command mode before navigating, editing with command keys, or saving. From there, :w saves, :wq saves and exits, and :q! discards unsaved changes.

I originally published a more detailed version of this guide on the SSHFlow blog.

I'm also building SSHFlow — an SSH client where every server gets its own workspace for terminals, SFTP, code, and databases.