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 &mdash; 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  and   do different things. This means, that if a command or a part of it is shown in uppercase, use of the  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
 * the 'Toggle keyboard' command &mdash; 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  key.

How to quit Vim Touch

 * Press the menu key on the phone, touch the  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  key and type

Yes, you have to type the colon  and the letter   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  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  or , and press   key to go back to command mode.
 * If unsure of which mode you are in, press  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  (aka  ) 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  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  key can be pressed several times to access commands stored in reverse chronological order (newest to oldest).


 * — search history
 * — general command history
 * — search/replace (substitution) history
 * — history for substitutions performed across the whole file
 * — 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:


 * — 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  menuitem.

Saving files
Although UNIX/Linux operating systems have a long-time practice of having a default home directory in the form of, the Android operating system that uses the Linux kernel, uses.

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


 * &bull;  may mean any file extension. For text files, it's.
 * 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 &mdash; including VimTouch &mdash; that can handle such a file.
 * &bull; As a mnemonic, it's convenient to save text files edited in Vim as . 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.
 * &#x26A0; Note, that unless it's a script or a plugin for Vim, it's not recommended to save normal text files as, because Vim handles files with a .vim extension differently.

Insert mode–or writing text

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


 * — start writing text from the beginning of a line
 * — 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 --

To unset it, use

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  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   &mdash; this increases minimum window size to 5 screen lines.


 * — move cursor one word forward
 * — move cursor one word back


 * — move cursor five words forward
 * — move cursor ten words back

You can use any other number.


 * — go to beginning of file and the first character of the first line
 * — 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  key screen, use   and   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,  ,  , and   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


 * — move the cursor three sentences up
 * — 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 —


 * — move cursor one screen line down
 * — 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:


 * — Goes to the 3000th character in a line

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

— invoke visual mode, and then use text motion keys described above to select text, such as:
 * and then press  or   multiple times to select a number of words before or after the cursor.
 * — select the next five words
 * +  or   arrows on the keyboard to select several lines.

— select all
 * ^  goes to beginning of file,   selects one line,   extends selection to the end of a file.

— 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.


 * ,,   (or  ) are for cutting, copying and pasting within Vim


 * means 'yank'
 * is for 'delete', but works as 'Cut'

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


 * — cut
 * — copy
 * — paste &mdash; or

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  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
— 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.

— redo

Join, sort

 * — joins next line to current line and removes all spaces in-between.
 * &bull; To join lines throughout the whole file (all lines), text must be selected first with


 * — 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.


 * and then press  to search for 'searchabletext'
 * and then press  to search for 'searchabletext'


 * Search results (all matches) are highlighted by default.
 * &mdash; switches off search result highlighting


 * To go to next search result, use the  key.
 * &bull; The movement is down, and upon reaching the last match, can continue from the top of the file.
 * &bull; Upwards movement to the 'previous' match is with the  combination.


 * To reuse a previously-used search, use the slash  and press the   key to display a previously-used search command;
 * &bull; You can use the  key several times to get to the desired previous search, or
 * &bull; type in the beginning parts of a previous search (starting with the slash character), and then press the  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:
 * &bull; This essentially finds all matches of 'searchabletext' and replaces it with 'textthatreplacesit'
 * &bull; The normal slash  serves as a separator. To search for something containing a slash, the slash must escaped with a backslash:
 * &bull; The letter  stands for substitute
 * &bull; The letter  stands for substitute


 * To search across a file, use the percent  character:
 * Finds 'apples' and replaces them with 'oranges'.
 * You won't need the percent character, if the file contains only one line.
 * 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:
 * &bull; The comma  is escaped with a backslash   to make sure it's treated as text:
 * &bull; 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.
 * &bull;  stands for newline, but is entered in the query as    (aka  /return key)
 * &bull;  after the slash   searches throughout the line to match all occurrences in the line.
 * &bull;  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.


 * — highlights Wikipedia syntax. This requires script/plugin; see here for more.
 * — highlights JavaScript code. This can cause temporary flickering when switching between other apps and Vim, and toggling the virtual keyboard on and 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:

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