Tutorial

Basic movements

You can use Vim's traditional movement keys, hjkl, to move the cursor:

They move the cursor in the same way that arrow keys do. Many newcomers to Vim/Vem find difficult to get used to them at first since the don't look very intuitive. It requires some initial effort to get familiar with them but it is very important to do it, mainly for two reasons: first, to move the cursor, you don't have to take your hands away from the home row of the keyboard and, second, many other actions in Vem are placed in the keyboard according to these movements (remember that Vem distributes commands in a spatial way across the keyboard). In sum, using these keys is part of an efficient use of Vem.

For example, the uppercase version of these letters just performs a larger movement in the same direction:

And you can also use them modified with Ctrl to start insert mode at the left, right, above and below the current line:

Other horizontal movements

These are movements that you can use to move inside the current line:

Other vertical movements

These movements will perform larger jumps up and down the current document:

Going back

You can make the cursor go back to the location it was before a jump with:

R:

jump back. Pressing it multiple times takes the cursor through the jump history, making it visit all the locations in the current file you have jumped to sequentially.

For example, you could jump to the beginning of a source code file, add some import/include/require statement and go back to the initial location by pressing R to continue editing where you were previously.

Deselecting and Reselecting

To stop a selection and go back to normal mode and to reselect the latest selected text use:

Space:

(in visual mode) deselect

Space Space:

(in normal mode) reselect

Quick selections

While you can create any arbitrary selection using G and movement actions, in practice it is very common to select specific text objects. For those, you can use the following shortcuts:

g:

select word

g g:

like g but for all characters surrounded by white space under the cursor (including parenthesis, brackets and punctuation)

Ctrl-g:

select text between enclosing quotes, parenthesis or brackets. Repeated presses to Ctrl-g expands the selection to the next enclosing pair of quotes, parenthesis or brackets.

Space a:

select all

Space p:

select current paragraph

There are many more selecting actions. Take a look at the Selecting section for a complete list.

Using the clipboard

Now that you know how to define a selection, it is a good moment to learn how to use the clipboard. Some basic actions that you can perform over a selection are:

e:

copy

d:

cut

c:

delete

p:

paste

As you can see, Vem does not use the common Ctrl-x, Ctrl-c and Ctrl-v shortcuts. This is on purpose, and although it may feel strange not to use them at first, after a bit of practice you'll notice how fast and comfortable are Vem's mappings in comparison.

Another thing to take into account is that p behaves differently depending on the kind of selection that was copied or cut. For example, if you have a linewise selection, lines will be pasted entirely without altering the existing ones (you don't have to open space for them). Characterwise selections behave closer to how they do in other text editors.

Using the secondary clipboard

Vem has two clipboards. The main clipboard (accessed with e, d and p) is connected to the system one so you can copy and paste information from/to other applications. The secondary clipboard allows you to have an additional piece of text in memory without overwriting whatever you have in the main one. You can access it with:

E:

copy (secondary clipboard)

D:

cut (secondary clipboard)

P:

paste (secondary clipboard)

Directional paste

Unlike other editors, Vem pastes content after the cursor by default (both for characterwise and linewise selections). To paste before the cursor you can use:

Ctrl-p h:

paste to the left of the cursor

Ctrl-p k:

paste above the cursor

Changing text

In other cases, you may want to delete some text and start insert mode immediately after (what it is known as changing in Vim terms). In the same way that the g key allows to perform quick selections, f allows you to to perform quick changes:

f:

delete word under cursor and start insert mode

F:

delete from cursor to the end of line and start insert mode

Ctrl-f:

delete text between next enclosing quotes, parenthesis or brackets and start insert mode

Searching the word under cursor

Sometimes, you just want to find the next occurrence of a term that is already present in the document. In those cases, just place the cursor on top of the word to search and use:

_:

search occurrences of the word under the cursor

Using the file browser

When you indicate that you want to open a file, a file browser is displayed:

As you can see, the file browser is very minimalistic and uses the same window where you edit your files. Don't let this simple appearance mislead you: while the functionality is very basic —pretty much just opening files— it is extremely fast to use, in particular because you can use any movement key that you use when editing files.

There are two movement keys that change their behavior when used inside the file browser though:

h:

go to parent directory

l:

open the file under the cursor (if the cursor is over a directory, the directory contents are displayed instead)

Other than that you can go up and down, jump to the top or the bottom of the list or search inside it using the same keys that you would use normally. When you find the file you want to open just press l or Enter.

A couple of additional commands that are very useful inside the file browser are:

Ctrl-h:

toggle the display of hidden files on / off

Ctrl-r:

refresh content

To leave the file browser without opening a file, use:

x:

close file browser

Creating a new file

You can create a new file with:

Ctrl-t:

new file

When a new file is created it doesn't have a name nor it is saved on disk. When you press s to save for the first time you will be prompted for its filename.

Switching files

When there are multiple open files in the editor, the tabline —a line at the top showing all their names— is displayed, and the current file is highlighted:

To switch from one file to another you can use:

t:

next file

T:

previous file

Or you can directly jump to a particular file by pressing:

When you do so, a new prompt and a list of results appear at the bottom of the editor. That is the fuzzy finder and it allows you to type the name of the file that you want to jump to:

The fuzzy finder allows you to type a few characters that can be found anywhere in the filename and will show the files that match your input characters in the top list. The characters don't have to necessarily be at the beginning of the filename nor be consecutive.

Once the filename you're looking for is highlighted in the top list of results, you can press Enter to switch to it.

If the file you're looking for is already being shown in the result list you can select it by using the following key mappings before pressing Enter:

Ctrl-k:

move up the result list in fuzzy finder

Ctrl-j:

move down the result list in fuzzy finder

This system works specially well when you have many open files because jumping from one to another just requires a few keystrokes.

To close the fuzzy finder without switching from the current file, use Ctrl-o or Esc.

Saving and closing all files

Finally, you may want to save all unsaved files or just close all files (and effectively leaving Vem). You can do so with:

Space s:

save all

Space x:

close all (exit Vem)

To execute them, you first have to press Space and then s or x in sequence.

Indenting

To indent or unindent the current selection, or just the current line if there's no selection active, use:

Tab:

indent current line or selection

Shift-Tab:

unindent current line or selection

Commenting

You can comment pieces of code out with v. If there's a visual selection, then all the lines in the visual selection are commented out. If there's no visual selection then only the current line will be commented out:

v:

comment and uncomment code (line comment symbols)

v acts as a toggle key so it can be used to both comment and uncomment code. If the lines in a selection are already commented out, v will remove all the comment symbols and, conversely, it will comment out all lines if they are not like that already.

To use block comment symbols, instead of line comment ones, use V:

V:

comment and uncomment code (block comment symbols)

The editor is able to automatically use the correct comment symbols for most common, and not so common, programming languages and markup files. However, if your file comment symbols are not detected correctly, take a look at the Comments section for possible solutions.

Replacing characters

Sometimes you need to change just a single character by another one. In those cases, you can just press r, when the cursor is over the character to be replaced, followed by the new one:

r{char}:

replace the character under the cursor with char. If there's a visual selection active, all the characters in the selection are replaced by char.

Toggle case

You can toggle the case of a character or a selection without leaving normal mode with:

Ctrl-u:

toggle case (lowercase/uppercase) of the character under the cursor or the text in the currently active selection.

Adding whitespace

You can add a blank space both in front or after the cursor (like pressing Space in insert mode) with:

(:

add a space to the left of the cursor

):

add a space to the right of the cursor

And you can also add blank lines both above and under the cursor too:

Joining/Splitting lines

&:

join the next line with the current one (removes the line break). If there's a visual selection active, join all the lines in the selection.

|:

introduce line breaks in a line or selection to adjust the text to a maximum width. This maximum with is equal to the value of the textwidth option if it is not set to zero. Otherwise, it is set to 79 characters (or to the screen width, if the editor screen is smaller than that number).

The commands to join and split lines are specially useful when editing regular text (as opposed to code).

Adding/Substracting units to numbers

Unintended changes

It can happen —specially when learning Vem, but also later too— that you mistakenly press a different key than the one you really intended to use. Since every key has an associated action, you may end up in an unexpected place of your document or modifying it in an unintentional way.

If this happens, just jump back to where you were or undo the latest action with:

q:

undo last change

R:

jump to previous position

q undoes the last change and jumps back too, so you can use that one to ensure that you didn't modify anything by mistake and if the latest change was correct you can just redo it with Q.

In any case, you can also check the timestamps of the latest changes to see, at any time, when the last change to the document happened:

:undolist

Getting help

You can get help about any topic using the command line. Just type:

:help <topic>

With Tab you can autocomplete the topic string.

You can use the help command to find more information about configuration options, commands or mappings. For example, you can get more information about the :sort ex-command with:

:help :sort

After executing this command, the screen will be split showing your current document and a new window displaying the contents of help. You can move in this window using the same movement keys as in the rest of the editor. In addition, you can:

• jump to a topic by placing the cursor on top of a highlighted term and pressing Space o

• jump back to the previous topic with Space i

• close the window with x