Learning the vi Editor/Vim/Vim Touch

For general information about, and history of Vim, see its corresponding article in Wikipedia.

Vim Touch (also VimTouch) is a powerful text editor based on Vim ported to the Android operating system, which OS runs on more than one billion individual devices, of which most of them are mobile phones.

This tutorial is about how to use Vim Touch, the useful commands one might immediately need, user interface walkthroughs and certain use case scenarios that are specific to Vim Touch on mobile devices.

The tutorial should be helpful to people who are beginners to Vim, but expects some familiarity with it, such as users, who already know the basics, but would prefer to skip most lists of commands. Although useful, seeing whole lists of Vim commands can be overwhelming to beginners who would want to do work with Vim right away.

So, one could also consider this a primer or a small handbook.

Usage notes and Prerequisites

Some computer proficiency is required, as this tutorial won't cover all use cases.

An additional option to learn Vim and its common commands on the fly — is to install gVim on a PC. gVim (graphical Vim) runs in a graphical environment, and is available for most computer operating systems. In graphical Linux or BSD distributions, gVim might already be installed.

gVim shows a traditional menu bar with menus containing the most common commands and their corresponding keyboard shortcuts. gVim would thus serve like a live visual aid.

Commands in Vim are case-sensitive, such that gj and gJ do different things. This means, that if a command or a part of it is shown in uppercase, use of the Shift key should be assumed by default. In command mode, the same character can mean different things for regular commands, and colon-based commands.

Commands native to Vim will work there, too.

Availability

Vim Touch is available from Google Play Store and the F-Droid app repository of free and open source (FOSS) apps. F-Droid has its own 'store' app to download FOSS apps from its repository, as well as from other repos that use infrastructure based on F-Droid.

The recommended virtual keyboard app for use with Vim Touch is Hacker's Keyboard, as it contains all the necessary keys on display on the first keyboard screen — keys, that are absent from the main screen of traditional Android keyboards. The Hacker's Keyboard app is also available from the F-Droid repository.

For heavy-duty work, a Bluetooth keyboard is recommended.

Specifics of Vim Touch

As a text-based app, VimTouch utilises text commands and heavy use of the keyboard. VimTouch improves on this by having its own menus, touch-based movement across the screen, and a customisable command bar for frequently-used commands.

Unlike most text editors in Android, Vim Touch starts as a service. This has many advantages, as it prevents a situation, where a user would have to frequently save their file in a basic text editor and start the app again, if they are multitasking in another app, and the basic text editor has quit in the meantime. That often happens in devices with insufficient RAM memory.

App menu and command bar

Pressing the hardware or virtual menu key on the phone invokes the app menu, which contains some of the following:

the quit command :q!
the 'Toggle keyboard' command — toggles the virtual keyboard
The extended app menu (at 'More') contains commands to open files through a filepicker, edit the .vimrc configuration file, and modify the command bar—which is also a simple text file.

The sliding command bar is useful both for frequently-used commands, and for commands that require several keystrokes. The command bar is pre-filled by default, but can be changed according to user preferences.

For example, people using non-US keyboard layouts are likely to populate the command bar with commands using characters that require frequent use of the Shift key.

How to quit Vim Touch

Press the menu key on the phone, touch the :q! menuitem. That's how simple it is.

Otherwise, it is usual for text-based Unix and Linux programs not to show instructions on how to quit them. This also includes Vim's predecessor vi, but Vim is different in this case:

At startup, Vim proper shows its version, author name and instructions to quit. If you don't see that, but want to quit the app, then —

press Esc key and type :q!

Yes, you have to type the colon : and the letter q and the exclamation mark !.

The exclamation mark is optional, and is used, if there are unsaved changes in a file, but you want to quit anyway.

Modal editing

Vim has several modes of operation: two of these being the edit mode and command mode. In the former, one edits text; and in the latter, one uses the keyboard to move through text and enter commands to manipulate text, search, replace, sort, and more.

Vim has more modes, but we'll concentrate on these two for the time being.

If you're not editing text, it's useful to switch to command mode with Esc key.

Command mode

At launch, Vim defaults to command mode. In command mode, a number of keys can be used to switch between modes, move around and manipulate text.

Edit text with i or a, and press Esc key to go back to command mode.
If unsure of which mode you are in, press Esc key once or twice to get to command mode.

More important commands require writing a colon : and a command, and optionally a number of parameters after that.

Colon-based commands require pressing the Enter (aka Return) key, and are needed for search and replace, file open and save, sorting and more.
Note, that Caps Lock affects which commands are entered, as upper-case commands differ from lower-case commands.

Command history

Vim preserves command histories, so it's easy to go back to previous commands with the Up key and repeat or modify one or more previously-used commands, whether they were successful or not. The command history is useful on a mobile device with a virtual keyboard, as it reduces the need to type excessively.

The Up key can be pressed several times to access commands stored in reverse chronological order (newest to oldest).

/ Up — search history

: Up — general command history

:s Up — search/replace (substitution) history

:%s Up — history for substitutions performed across the whole file

:w Up — save history

If a more complex command has been used, then it's possible to get to it faster by writing the first parts of it:

/wik Up — if a previous search looked for 'Wikipedia', then using this combination may display the full command.

Opening files

Vim Touch allows files to be opened from the app menu and the filepicker: use the device menu key, then tap 'More' for a longer list of commands. Choose one of the open commands, and from the app list, tap on 'Choose file'.

The file is then opened in a new Vim window. The user can choose to keep the empty file, or tap into its window to focus on it, and close that file/window by using the :q! menuitem.

Saving files

Although UNIX/Linux operating systems have a long-time practice of having a default home directory in the form of <root>/home/username, the Android operating system that uses the Linux kernel, uses /data/media/<userid>.

Users can create their own folder in the root directory, and /home is often the shortest and most meaningful folder name. Thus, the folder would be located in /sdcard/home (in Android 2.3). Saving in Vim Touch to that path:

:w /sdcard/home/filename.ext

• .ext may mean any file extension. For text files, it's .txt.

It's important to save a file with an extension, as it allows Android to recognise the type of file and offer a number of suggested apps — including VimTouch — that can handle such a file.

• As a mnemonic, it's convenient to save text files edited in Vim as filename.vim.txt. This would later allow seeing in the file manager, that the file was edited in Vim, and the user can then choose to open the file in Vim.

⚠ Note, that unless it's a script or a plugin for Vim, it's not recommended to save normal text files as filename.vim, because Vim handles files with a .vim extension differently.

Insert mode–or writing text

i — start writing (insert|ing) text before a character under block cursor

a — start writing (append|ing) text after a character under block cursor

I — start writing text from the beginning of a line

A — start writing text from the end of a line

The text cursor also has different behaviors. In command mode, the text cursor is a block, and in insert/append mode, the text cursor can be an I-beam. The appearance can differ from configuration to configuration, but is mostly uniform.

Legibility

For the purpose of legibility, and to compose text, set word wrapping --

:set lbr

To unset it, use

:set lbr!

Setting word wrapping increases the virtual length of a line, as it takes up more screen space.

Moving around text

Vim Touch uses the functionality of touch-enabled displays, and thus offers some features not available in regular Vim installations:

Access to the app menu for primary commands;
Access to the extended app menu containing more useful commands;
Users can tap to place the cursor on the (near-)exact part of text on the screen that the user wants to work with.
In command mode, it's possible to touch-slide the display area to scroll up or down. This may or may not work smoothly.

In insert/editing mode, avoid sliding fingers across the screen, since it's interpreted as input, and you might accidentally input lots of gibberish. This can be undone by escaping into command mode, and using the undo u command.

Using the keyboard

In Vim Touch, press the device menu key, and then the 'Toggle virtual keyboard' menuitem to show the keyboard.

The appearance of the keyboard reduces the Vim viewport size, and if there are more than one windows open in Vim, then this can reduce the size of the bottom-most window to just one line. The workaround to that is Ctrl+w5_ — this increases minimum window size to 5 screen lines.

w — move cursor one word forward

b — move cursor one word back

5w — move cursor five words forward

10b — move cursor ten words back

You can use any other number.

gg — go to beginning of file and the first character of the first line

G — go to end of file and the beginning of last line. (YMMV; could be the end of last line, too.)

When using Hacker's Keyboard:

In the second Fn key screen, use PgUp and PgDn keys to move up and down a page. This works only with 'hard' lines, but not with one continuous long line.
The second key screen also contains Home, End, Ins, and Del keys, and a dedicated numeric keypad for easy input of larger numbers.

Moving across long lines

In a situation, where one has very long lines of text, a small-screen device, and a virtual keyboard, then moving the cursor in the screen requires several creative approaches, because up-down navigation happens from one actual text line to another.

( — move to beginning of sentence

) — move to end of sentence

This requires the presence of a period and a space .

3( — move the cursor three sentences up

4) — move the cursor four sentences down

In the absence of this...

Sometimes it's useful to go to the very next screen line, or several in a row. To display just these, for example. To do so, use —

gj — move cursor one screen line down

gk — move cursor one screen line up

Screen lines are sometimes called virtual lines.

Alternately, the Vim statusline (the status bar) usually shows the cursor position at column number, which is the number of characters from the beginning of a (long) line. One can remember a column number and go to it within a line:

:goto 3000 — Goes to the 3000th character in a line

Manipulating text

Visual mode—select text

Vim uses Visual mode to select text, and is invoked in command mode. Use Esc key to exit it.

v — invoke visual mode, and then use text motion keys described above to select text, such as:

v and then press b or w multiple times to select a number of words before or after the cursor.

v5w — select the next five words

v + up or down arrows on the keyboard to select several lines.

ggVG — select all

^ gg goes to beginning of file, V selects one line, G extends selection to the end of a file.

V — select the whole current line (one under cursor).

Once text is selected, the user can cut, copy, paste over, or otherwise manipulate text.
It's also possible to perform search-replace, join, or sort operations within that selection.

Cut, copy, paste, and delete

Vim has several ways to do those things, and internal and external copy-paste commands are compartmentalised to within Vim and outside of it. This works in command mode.

Note, that cutting and copying often requires that text is already selected in Visual mode.

x, y, p (or P) are for cutting, copying and pasting within Vim

y means 'yank'

d is for 'delete', but works as 'Cut'

Outside of that, there are key sequences to copy-paste between Vim and other apps —

"*x — cut

"*y — copy

"*p — paste — or "*P

So, yes, one indeed has to type straight double quotes ", an asterisk * and the letter corresponding to the operation. Because these commands may require pressing the Shift key in many non-US keyboard layouts, it's better to put one or two of them into the command bar in Vim Touch.

One can replace a block of text selected in visual mode by pasting atop it.

Undo and Redo

u — undo, for as many undo steps as you like.

One undo step applies to all text manipulated in insert mode. That is why, if at the moment you're not editing text, it's important to switch (or default) to command mode. This keeps undo steps more granular.

Ctrl+R — redo

Join, sort

gJ — joins next line to current line and removes all spaces in-between.

• To join lines throughout the whole file (all lines), text must be selected first with ggVG

:sort — If you have a list of lines, then the list is sorted following the order of ASCII and Unicode code points. This applies to all lines in a file. For only parts of text, use Visual mode to select a block of text and then sort within it.

Search

Use the slash / to search. Vim uses regular expressions, which allow complex searching.

/searchabletext

and then press Enter to search for 'searchabletext'

Search results (all matches) are highlighted by default.

:noh — switches off search result highlighting

To go to next search result, use the n key.

• The movement is down, and upon reaching the last match, can continue from the top of the file.

• Upwards movement to the 'previous' match is with the Shift+n combination.

To reuse a previously-used search, use the slash / and press the Up key to display a previously-used search command;

• You can use the Up key several times to get to the desired previous search, or

• type in the beginning parts of a previous search (starting with the slash character), and then press the Up key. This universally applies to search-and-replace operations, too.

Search and replace

This also uses regular expressions, and makes it possible to perform complex manipulations of text.

The simple of it:

:s/searchabletext/textthatreplacesit

• This essentially finds all matches of 'searchabletext' and replaces it with 'textthatreplacesit'

• The normal slash / serves as a separator. To search for something containing a slash, the slash must escaped with a backslash: \/

• The letter s stands for substitute

To search across a file, use the percent % character:

:%s/apples/oranges

Finds 'apples' and replaces them with 'oranges'.

You won't need the percent character, if the file contains only one line.

If one (very) long line contains several commas, and you'd want to place text after each comma into a new line:

:s/\,/&^M/g

• The comma , is escaped with a backslash \ to make sure it's treated as text: \,

• The ampersand & means addition of text instead of replacing it. Depending on where text is positioned relative to the ampersand, new content is added either before or after the search result; In this case, content is added after a comma.

• ^M stands for newline, but is entered in the query as Ctr+VEnter (aka <cr>/return key)

• g after the slash / searches throughout the line to match all occurrences in the line.

Syntax highlighting

Vim is also a tool for programmers, web developers, and Wikipedia editors, as it supports syntax highlighting, which color-codes different parts of text-based formatting or code, thus allowing people to see whether the displayed code is correctly written. If a particular syntax is not supported, it can be installed as a plugin in script form.

:setf wikimedia — highlights Wikipedia syntax. This requires script/plugin; see here for more.
:setf javascript — highlights JavaScript code. This can cause temporary flickering when switching between other apps and Vim, and toggling the virtual keyboard on and off.
:syn off — turns syntax highlighting off

In Vim Touch, JavaScript syntax highlighting works only to up to the 3000th character in one line. On old or basic Android devices, syntax highlighting can be slow. Some syntax highlighting can cause temporary flickering of app content.

A separately-installed syntax script (such as for mediawiki), must be located in this path in Android 2.3:

/sdcard/.vim/syntax/mediawiki.vim

If these folders are not yet present, they must be created with a file manager or in a terminal app, such as Terminal Emulator.