VIM USER MANUAL - by Bram Moolenaar *usr_toc.txt* For Vim version 6.1. Last change: 2002 Mar 09 Table Of Contents *user-manual* ============================================================================== Overview ~ Getting Started |usr_01.txt| About the manuals |usr_02.txt| The first steps in Vim |usr_03.txt| Moving around |usr_04.txt| Making small changes |usr_05.txt| Set your settings |usr_06.txt| Using syntax highlighting |usr_07.txt| Editing more than one file |usr_08.txt| Splitting windows |usr_09.txt| Using the GUI |usr_10.txt| Making big changes |usr_11.txt| Recovering from a crash |usr_12.txt| Clever tricks Editing Effectively |usr_20.txt| Typing command-line commands quickly |usr_21.txt| Go away and come back |usr_22.txt| Finding the file to edit |usr_23.txt| Editing other files |usr_24.txt| Inserting quickly |usr_25.txt| Editing formatted text |usr_26.txt| Repeating |usr_27.txt| Search commands and patterns |usr_28.txt| Folding |usr_29.txt| Moving through programs |usr_30.txt| Editing programs |usr_31.txt| Exploiting the GUI Tuning Vim |usr_40.txt| Make new commands |usr_41.txt| Write a Vim script |usr_42.txt| Add new menus |usr_43.txt| Using filetypes |usr_44.txt| Your own syntax highlighted |usr_45.txt| Select your language Making Vim Run |usr_90.txt| Installing Vim The user manual is available as a single, ready to print HTML and PDF file here: http://vimdoc.sf.net ============================================================================== Getting Started ~ Read this from start to end to learn the essential commands. |usr_01.txt| About the manuals |01.1| Two manuals |01.2| Vim installed |01.3| Using the Vim tutor |01.4| Copyright |usr_02.txt| The first steps in Vim |02.1| Running Vim for the First Time |02.2| Inserting text |02.3| Moving around |02.4| Deleting characters |02.5| Undo and Redo |02.6| Other editing commands |02.7| Getting out |02.8| Finding help |usr_03.txt| Moving around |03.1| Word movement |03.2| Moving to the start or end of a line |03.3| Moving to a character |03.4| Matching a paren |03.5| Moving to a specific line |03.6| Telling where you are |03.7| Scrolling around |03.8| Simple searches |03.9| Simple search patterns |03.10| Using marks |usr_04.txt| Making small changes |04.1| Operators and motions |04.2| Changing text |04.3| Repeating a change |04.4| Visual mode |04.5| Moving text |04.6| Copying text |04.7| Using the clipboard |04.8| Text objects |04.9| Replace mode |04.10| Conclusion |usr_05.txt| Set your settings |05.1| The vimrc file |05.2| The example vimrc file explained |05.3| Simple mappings |05.4| Adding a plugin |05.5| Adding a help file |05.6| The option window |05.7| Often used options |usr_06.txt| Using syntax highlighting |06.1| Switching it on |06.2| No or wrong colors? |06.3| Different colors |06.4| With colors or without colors |06.5| Printing with colors |06.6| Further reading |usr_07.txt| Editing more than one file |07.1| Edit another file |07.2| A list of files |07.3| Jumping from file to file |07.4| Backup files |07.5| Copy text between files |07.6| Viewing a file |07.7| Changing the file name |usr_08.txt| Splitting windows |08.1| Split a window |08.2| Split a window on another file |08.3| Window size |08.4| Vertical splits |08.5| Moving windows |08.6| Commands for all windows |08.7| Viewing differences with vimdiff |08.8| Various |usr_09.txt| Using the GUI |09.1| Parts of the GUI |09.2| Using the mouse |09.3| The clipboard |09.4| Select mode |usr_10.txt| Making big changes |10.1| Record and playback commands |10.2| Substitution |10.3| Command ranges |10.4| The global command |10.5| Visual block mode |10.6| Reading and writing part of a file |10.7| Formatting text |10.8| Changing case |10.9| Using an external program |usr_11.txt| Recovering from a crash |11.1| Basic recovery |11.2| Where is the swap file? |11.3| Crashed or not? |11.4| Further reading |usr_12.txt| Clever tricks |12.1| Replace a word |12.2| Change "Last, First" to "First Last" |12.3| Sort a list |12.4| Reverse line order |12.5| Count words |12.6| Find a man page |12.7| Trim blanks |12.8| Find where a word is used ============================================================================== Editing Effectively ~ Subjects that can be read independently. |usr_20.txt| Typing command-line commands quickly |20.1| Command line editing |20.2| Command line abbreviations |20.3| Command line completion |20.4| Command line history |20.5| Command line window |usr_21.txt| Go away and come back |21.1| Suspend and resume |21.2| Executing shell commands |21.3| Remembering information; viminfo |21.4| Sessions |21.5| Views |21.6| Modelines |usr_22.txt| Finding the file to edit |22.1| The file explorer |22.2| The current directory |22.3| Finding a file |22.4| The buffer list |usr_23.txt| Editing other files |23.1| DOS, Mac and Unix files |23.2| Files on the internet |23.3| Encryption |23.4| Binary files |23.5| Compressed files |usr_24.txt| Inserting quickly |24.1| Making corrections |24.2| Showing matches |24.3| Completion |24.4| Repeating an insert |24.5| Copying from another line |24.6| Inserting a register |24.7| Abbreviations |24.8| Entering special characters |24.9| Digraphs |24.10| Normal mode commands |usr_25.txt| Editing formatted text |25.1| Breaking lines |25.2| Aligning text |25.3| Indents and tabs |25.4| Dealing with long lines |25.5| Editing tables |usr_26.txt| Repeating |26.1| Repeating with Visual mode |26.2| Add and subtract |26.3| Making a change in many files |26.4| Using Vim from a shell script |usr_27.txt| Search commands and patterns |27.1| Ignoring case |27.2| Wrapping around the file end |27.3| Offsets |27.4| Matching multiple times |27.5| Alternatives |27.6| Character ranges |27.7| Character classes |27.8| Matching a line break |27.9| Examples |usr_28.txt| Folding |28.1| What is folding? |28.2| Manual folding |28.3| Working with folds |28.4| Saving and restoring folds |28.5| Folding by indent |28.6| Folding with markers |28.7| Folding by syntax |28.8| Folding by expression |28.9| Folding unchanged lines |28.10| Which fold method to use? |usr_29.txt| Moving through programs |29.1| Using tags |29.2| The preview window |29.3| Moving through a program |29.4| Finding global identifiers |29.5| Finding local identifiers |usr_30.txt| Editing programs |30.1| Compiling |30.2| Indenting C files |30.3| Automatic indenting |30.4| Other indenting |30.5| Tabs and spaces |30.6| Formatting comments |usr_31.txt| Exploiting the GUI |31.1| The file browser |31.2| Confirmation |31.3| Menu shortcuts |31.4| Vim window position and size |31.5| Various ============================================================================== Tuning Vim ~ Make Vim work as you like it. |usr_40.txt| Make new commands |40.1| Key mapping |40.2| Defining command-line commands |40.3| Autocommands |usr_41.txt| Write a Vim script |41.1| Introduction |41.2| Variables |41.3| Expressions |41.4| Conditionals |41.5| Executing an expression |41.6| Using functions |41.7| Defining a function |41.8| Various remarks |41.9| Writing a plugin |41.10| Writing a filetype plugin |41.11| Writing a compiler plugin |usr_42.txt| Add new menus |42.1| Introduction |42.2| Menu commands |42.3| Various |42.4| Toolbar and popup menus |usr_43.txt| Using filetypes |43.1| Plugins for a filetype |43.2| Adding a filetype |usr_44.txt| Your own syntax highlighted |44.1| Basic syntax commands |44.2| Keywords |44.3| Matches |44.4| Regions |44.5| Nested items |44.6| Following groups |44.7| Other arguments |44.8| Clusters |44.9| Including another syntax file |44.10| Synchronizing |44.11| Installing a syntax file |44.12| Portable syntax file layout |usr_45.txt| Select your language |45.1| Language for Messages |45.2| Language for Menus |45.3| Using another encoding |45.4| Editing files with a different encoding |45.5| Entering language text ============================================================================== Making Vim Run ~ Before you can use Vim. |usr_90.txt| Installing Vim |90.1| Unix |90.2| MS-Windows |90.3| Upgrading |90.4| Common installation issues |90.5| Uninstalling Vim ============================================================================== *usr_01.txt* For Vim version 6.1. Last change: 2002 Jan 15 About the manuals This chapter introduces the manuals available with Vim. Read this to know the conditions under which the commands are explained. |01.1| Two manuals |01.2| Vim installed |01.3| Using the Vim tutor |01.4| Copyright ============================================================================== *01.1* Two manuals The Vim documentation consists of two parts: 1. The User manual Task oriented explanations, from simple to complex. Reads from start to end like a book. 2. The Reference manual Precise description of how everything in Vim works. The notation used in these manuals is explained here: |notation| JUMPING AROUND The text contains hyperlinks between the two parts, allowing you to quickly jump between the description of an editing task and a precise explanation of the commands and options used for it. Use these two commands: Press CTRL-] to jump to a subject under the cursor. Press CTRL-O to jump back (repeat to go further back). Many links are in vertical bars, like this: |bars|. An option name, like 'number', a command in double quotes like ":write" and any other word can also be used as a link. Try it out: Move the cursor to CTRL-] and press CTRL-] on it. Other subjects can be found with the ":help" command, see |help.txt|. ============================================================================== *01.2* Vim installed Most of the manuals assume that Vim has been properly installed. If you didn't do that yet, or if Vim doesn't run properly (e.g., files can't be found or in the GUI the menus do not show up) first read the chapter on installation: |usr_90.txt|. *not-compatible* The manuals often assume you are using Vim with Vi-compatibility switched off. For most commands this doesn't matter, but sometimes it is important, e.g., for multi-level undo. An easy way to make sure you are using the right setup, copy the example vimrc file. By doing this inside Vim you don't have to check out where it is located. How to do this depends on the system you are using: Unix: > :!cp -i $VIMRUNTIME/vimrc_example.vim ~/.vimrc MS-DOS, MS-Windows, OS/2: > :!copy $VIMRUNTIME/vimrc_example.vim $VIM/_vimrc Amiga: > :!copy $VIMRUNTIME/vimrc_example.vim $VIM/.vimrc If the file already exists you probably want to keep it. If you start Vim now, the 'compatible' option should be off. You can check it with this command: > :set compatible? If it responds with "nocompatible" you are doing well. If the response is "compatible" you are in trouble. You will have to find out why the option is still set. Perhaps the file you wrote above is not found. Use this command to find out: > :scriptnames If your file is not in the list, check its location and name. If it is in the list, there must be some other place where the 'compatible' option is switched back on. For more info see |vimrc| and |compatible-default|. Note: This manual is about using Vim in the normal way. There is an alternative called "evim" (easy Vim). This is still Vim, but used in a way that resembles a click-and-type editor like Notepad. It always stays in Insert mode, thus it feels very different. It is not explained in the user manual, since it should be mostly self explanatory. See |evim-keys| for details. ============================================================================== *01.3* Using the Vim tutor *tutor* *vimtutor* Instead of reading the text (boring!) you can use the vimtutor to learn your first Vim commands. This is a 30 minute tutorial that teaches the most basic Vim functionality hands-on. On Unix and MS-Windows, if Vim has been properly installed, you can start it from the shell: > vimtutor This will make a copy of the tutor file, so that you can edit it without the risk of damaging the original. There are a few translated versions of the tutor. To find out if yours is available, use the two-letter language code. For French: > vimtutor fr On non-Unix systems, you have to do a little work: 1. Copy the tutor file. You can do this with Vim (it knows where to find it): > vim -u NONE -c 'e $VIMRUNTIME/tutor/tutor' -c 'w! TUTORCOPY' -c 'q' < This will write the file "TUTORCOPY" in the current directory. To use a translated version of the tutor, append the two-letter language code to the filename. For French: > vim -u NONE -c 'e $VIMRUNTIME/tutor/tutor.fr' -c 'w! TUTORCOPY' -c 'q' < 2. Edit the copied file with Vim: > vim -u NONE -c "set nocp" TUTORCOPY < The extra arguments make sure Vim is started in a good mood. 3. Delete the copied file when you are finished with it: > del TUTORCOPY < ============================================================================== *01.4* Copyright *manual-copyright* The Vim user manual and reference manual are Copyright (c) 1988-2002 by Bram Moolenaar. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later. The latest version is presently available at: http://www.opencontent.org/openpub/ People who contribute to the manuals must agree with the above copyright notice. *frombook* Parts of the user manual come from the book "Vi IMproved - Vim" by Steve Oualline (published by New Riders Publishing, ISBN: 0735710015). The Open Publication License applies to this book. Only selected parts are included and these have been modified (e.g., by removing the pictures, updating the text for Vim 6.0 and fixing mistakes). The omission of the |frombook| tag does not mean that the text does not come from the book. Many thanks to Steve Oualline and New Riders for creating this book and publishing it under the OPL! It has been a great help while writing the user manual. Not only by providing literal text, but also by setting the tone and style. If you make money through selling the manuals, you are strongly encouraged to donate part of the profit to help AIDS victims in Uganda. See |iccf|. ============================================================================== *usr_02.txt* For Vim version 6.1. Last change: 2001 Sep 03 The first steps in Vim This chapter provides just enough information to edit a file with Vim. Not well or fast, but you can edit. Take some time to practice with these commands, they form the base for what follows. |02.1| Running Vim for the First Time |02.2| Inserting text |02.3| Moving around |02.4| Deleting characters |02.5| Undo and Redo |02.6| Other editing commands |02.7| Getting out |02.8| Finding help ============================================================================== *02.1* Running Vim for the First Time To start Vim, enter this command: > gvim file.txt In UNIX you can type this at any command prompt. If you are running Microsoft Windows, open an MS-DOS prompt window and enter the command. In either case, Vim starts editing a file called file.txt. Because this is a new file, you get a blank window. This is what your screen will look like: +---------------------------------------+ |# | |~ | |~ | |~ | |~ | |"file.txt" [New file] | +---------------------------------------+ ('#" is the cursor position.) The tilde (~) lines indicate lines not in the file. In other words, when Vim runs out of file to display, it displays tilde lines. At the bottom of the screen, a message line indicates the file is named file.txt and shows that you are creating a new file. The message information is temporary and other information overwrites it. THE VIM COMMAND The gvim command causes the editor to create a new window for editing. If you use this command: > vim file.txt the editing occurs inside your command window. In other words, if you are running inside an xterm, the editor uses your xterm window. If you are using an MS-DOS command prompt window under Microsoft Windows, the editing occurs inside this window. The text in the window will look the same for both versions, but with gvim you have extra features, like a menu bar. More about that later. ============================================================================== *02.2* Inserting text The Vim editor is a modal editor. That means that the editor behaves differently, depending on which mode you are in. The two basic modes are called Normal mode and Insert mode. In Normal mode the characters you type are commands. In Insert mode the characters are inserted as text. Since you have just started Vim it will be in Normal mode. To start Insert mode you type the "i" command (i for Insert). Then you can enter the text. It will be inserted into the file. Do not worry if you make mistakes; you can correct them later. To enter the following programmer's limerick, this is what you type: > iA very intelligent turtle Found programming UNIX a hurdle After typing "turtle" you press the <Enter> key to start a new line. Finally you press the <Esc> key to stop Insert mode and go back to Normal mode. You now have two lines of text in your Vim window: +---------------------------------------+ |A very intelligent turtle | |Found programming UNIX a hurdle | |~ | |~ | | | +---------------------------------------+ WHAT IS THE MODE? To be able to see what mode you are in, type this command: > :set showmode You will notice that when typing the colon Vim moves the cursor to the last line of the window. That's where you type colon commands (commands that start with a colon). Finish this command by pressing the <Enter> key (all commands that start with a colon are finished this way). Now, if you type the "i" command Vim will display --INSERT-- at the bottom of the window. This indicates you are in Insert mode. +---------------------------------------+ |A very intelligent turtle | |Found programming UNIX a hurdle | |~ | |~ | |-- INSERT -- | +---------------------------------------+ If you press <Esc> to go back to Normal mode the last line will be made blank. GETTING OUT OF TROUBLE One of the problems for Vim novices is mode confusion, which is caused by forgetting which mode you are in or by accidentally typing a command that switches modes. To get back to Normal mode, no matter what mode you are in, press the <Esc> key. Sometimes you have to press it twice. If Vim beeps back at you, you already are in Normal mode. ============================================================================== *02.3* Moving around After you return to command mode, you can move around by using these keys: h left j down k up l right At first, it may appear that these commands were chosen at random. After all, who ever heard of using l for right? But actually, there is a very good reason for these choices: Moving the cursor is the most common thing you do in an editor, and these keys are on the home row of your right hand. In other words, these commands are placed where you can type them the fastest (especially when you type with ten fingers). Note: You can also move the cursor by using the arrow keys. If you do, however, you greatly slow down your editing because to press the arrow keys, you must move your hand from the text keys to the arrow keys. Considering that you might be doing it hundreds of times an hour, this can take a significant amount of time. Also, there are keyboards which do not have arrow keys, or which locate them in unusual places; therefore, knowing the use of the hjkl keys helps in those situations. One way to remember these commands is that h is on the left, l is on the right and j points down. In a picture: > k h l j The best way to learn these commands is by using them. Use the "i" command to insert some more lines of text. Then use the hjkl keys to move around and insert a word somewhere. Don't forget to press <Esc> to go back to Normal mode. The |vimtutor| is also a nice way to learn by doing. ============================================================================== *02.4* Deleting characters To delete a character, move the cursor over it and type "x". (This is a throwback to the old days of the typewriter, when you deleted things by typing xxxx over them.) Move the cursor to the beginning of the first line, for example, and type xxxxxxx (seven x's) to delete "A very ". The result should look like this: +---------------------------------------+ |intelligent turtle | |Found programming UNIX a hurdle | |~ | |~ | | | +---------------------------------------+ Now you can insert new text, for example by typing: > iA young <Esc> This begins an insert (the i), inserts the words "A young", and then exits insert mode (the final <Esc>). The result: +---------------------------------------+ |A young intelligent turtle | |Found programming UNIX a hurdle | |~ | |~ | | | +---------------------------------------+ DELETING A LINE To delete a whole line use the "dd" command. The following line will then move up to fill the gap: +---------------------------------------+ |Found programming UNIX a hurdle | |~ | |~ | |~ | | | +---------------------------------------+ DELETING A LINE BREAK In Vim you can join two lines together, which means that the line break between them is deleted. The "J" command does this. Take these two lines: A young intelligent ~ turtle ~ Move the cursor to the first line and press "J": A young intelligent turtle ~ ============================================================================== *02.5* Undo and Redo Suppose you delete too much. Well, you can type it in again, but an easier way exists. The "u" command undoes the last edit. Take a look at this in action: After using "dd" to delete the first line, "u" brings it back. Another one: Move the cursor to the A in the first line: A young intelligent turtle ~ Now type xxxxxxx to delete "A young". The result is as follows: intelligent turtle ~ Type "u" to undo the last delete. That delete removed the g, so the undo restores the character. g intelligent turtle ~ The next u command restores the next-to-last character deleted: ng intelligent turtle ~ The next u command gives you the u, and so on: ung intelligent turtle ~ oung intelligent turtle ~ young intelligent turtle ~ young intelligent turtle ~ A young intelligent turtle ~ Note: If you type "u" twice, and the result is that you get the same text back, you have Vim configured to work Vi compatible. Look here to fix this: |not-compatible|. This text assumes you work "The Vim Way". You might prefer to use the good old Vi way, but you will have to watch out for small differences in the text then. REDO If you undo too many times, you can press CTRL-R (redo) to reverse the preceding command. In other words, it undoes the undo. To see this in action, press CTRL-R twice. The character A and the space after it disappear: young intelligent turtle ~ There's a special version of the undo command, the "U" (undo line) command. The undo line command undoes all the changes made on the last line that was edited. Typing this command twice cancels the preceding "U". A very intelligent turtle ~ xxxx Delete very A intelligent turtle ~ xxxxxx Delete turtle A intelligent ~ Restore line with "U" A very intelligent turtle ~ Undo "U" with "u" A intelligent ~ The "U" command is a change by itself, which the "u" command undoes and CTRL-R redoes. This might be a bit confusing. Don't worry, with "u" and CTRL-R you can go to any of the situations you had. ============================================================================== *02.6* Other editing commands Vim has a large number of commands to change the text. See |Q_in| and below. Here are a few often used ones. APPENDING The "i" command inserts a character before the character under the cursor. That works fine; but what happens if you want to add stuff to the end of the line? For that you need to insert text after the cursor. This is done with the "a" (append) command. For example, to change the line and that's not saying much for the turtle. ~ to and that's not saying much for the turtle!!! ~ move the cursor over to the dot at the end of the line. Then type "x" to delete the period. The cursor is now positioned at the end of the line on the e in turtle. Now type > a!!!<Esc> to append three exclamation points after the e in turtle: and that's not saying much for the turtle!!! ~ OPENING UP A NEW LINE The "o" command creates a new, empty line below the cursor and puts Vim in Insert mode. Then you can type the text for the new line. Suppose the cursor is somewhere in the first of these two lines: A very intelligent turtle ~ Found programming UNIX a hurdle ~ If you now use the "o" command and type new text: > oThat liked using Vim<Esc> The result is: A very intelligent turtle ~ That liked using Vim ~ Found programming UNIX a hurdle ~ The "O" command (uppercase) opens a line above the cursor. USING A COUNT Suppose you want to move up nine lines. You can type "kkkkkkkkk" or you can enter the command "9k". In fact, you can precede many commands with a number. Earlier in this chapter, for instance, you added three exclamation points to the end of a line by typing "a!!!<Esc>". Another way to do this is to use the command "3a!<Esc>". The count of 3 tells the command that follows to triple its effect. Similarly, to delete three characters, use the command "3x". The count always comes before the command it applies to. ============================================================================== *02.7* Getting out To exit, use the "ZZ" command. This command writes the file and exits. Note: Unlike many other editors, Vim does not automatically make a backup file. If you type "ZZ", your changes are committed and there's no turning back. You can configure the Vim editor to produce backup files, see |07.4|. DISCARDING CHANGES Sometimes you will make a sequence of changes and suddenly realize you were better off before you started. Not to worry; Vim has a quit-and-throw-things-away command. It is: > :q! Don't forget to press <Enter> to finish the command. For those of you interested in the details, the three parts of this command are the colon (:), which enters command mode; the q command, which tells the editor to quit; and the override command modifier (!). The override command modifier is needed because Vim is reluctant to throw away changes. If you were to just type ":q", Vim would display an error message and refuse to exit: E37: No write since last change (use ! to override) ~ By specifying the override, you are in effect telling Vim, "I know that what I'm doing looks stupid, but I'm a big boy and really want to do this." If you want to continue editing with Vim: The ":e!" command reloads the original version of the file. ============================================================================== *02.8* Finding help Everything you always wanted to know can be found in the Vim help files. Don't be afraid to ask! To get generic help use this command: > :help You could also use the first function key <F1>. If your keyboard has a <Help> key it might work as well. If you don't supply a subject, ":help" displays the general help window. The creators of Vim did something very clever (or very lazy) with the help system: They made the help window a normal editing window. You can use all the normal Vim commands to move through the help information. Therefore h, j, k, and l move left, down, up and right. To get out of the help window, use the same command you use to get out of the editor: "ZZ". This will only close the help window, not exit Vim. As you read the help text, you will notice some text enclosed in vertical bars (for example, |help|). This indicates a hyperlink. If you position the cursor anywhere between the bars and press CTRL-] (jump to tag), the help system takes you to the indicated subject. (For reasons not discussed here, the Vim terminology for a hyperlink is tag. So CTRL-] jumps to the location of the tag given by the word under the cursor.) After a few jumps, you might want to go back. CTRL-T (pop tag) takes you back to the preceding position. CTRL-O (jump to older position) also works nicely here. At the top of the help screen, there is the notation *help.txt*. This name between "*" characters is used by the help system to define a tag (hyperlink destination). See |29.1| for details about using tags. To get help on a given subject, use the following command: > :help {subject} To get help on the "x" command, for example, enter the following: > :help x To find out how to delete text, use this command: > :help deleting To get a complete index of all Vim commands, use the following command: > :help index When you need to get help for a control character command (for example, CTRL-A), you need to spell it with the prefix "CTRL-". > :help CTRL-A The Vim editor has many different modes. By default, the help system displays the normal-mode commands. For example, the following command displays help for the normal-mode CTRL-H command: > :help CTRL-H To identify other modes, use a mode prefix. If you want the help for the insert-mode version of a command, use "i_". For CTRL-H this gives you the following command: > :help i_CTRL-H When you start the Vim editor, you can use several command-line arguments. These all begin with a dash (-). To find what the -t argument does, for example, use the command: > :help -t The Vim editor has a number of options that enable you to configure and customize the editor. If you want help for an option, you need to enclose it in single quotation marks. To find out what the 'number' option does, for example, use the following command: > :help 'number' The table with all mode prefixes can be found here: |help-context|. Special keys are enclosed in angle brackets. To find help on the up-arrow key in Insert mode, for instance, use this command: > :help i_<Up> If you see an error message that you don't understand, for example: E37: No write since last change (use ! to override) ~ You can use the error ID at the start to find help about it: > :help E37 ============================================================================== *usr_03.txt* For Vim version 6.1. Last change: 2002 Jan 31 Moving around Before you can insert or delete text the cursor has to be moved to the right place. Vim has a large number of commands to position the cursor. This chapter shows you how to use the most important ones. You can find a list of these commands below |Q_lr|. |03.1| Word movement |03.2| Moving to the start or end of a line |03.3| Moving to a character |03.4| Matching a paren |03.5| Moving to a specific line |03.6| Telling where you are |03.7| Scrolling around |03.8| Simple searches |03.9| Simple search patterns |03.10| Using marks ============================================================================== *03.1* Word movement To move the cursor forward one word, use the "w" command. Like most Vim commands, you can use a numeric prefix to move past multiple words. For example, "3w" moves three words. This figure shows how it works: This is a line with example text ~ --->-->->-----------------> w w w 3w Notice that "w" moves to the start of the next word if it already is at the start of a word. The "b" command moves backward to the start of the previous word: This is a line with example text ~ <----<--<-<---------<--- b b b 2b b There is also the "e" command that moves to the next end of a word and "ge", which moves to the previous end of a word: This is a line with example text ~ <- <--- -----> ----> ge ge e e If you are at the last word of a line, the "w" command will take you to the first word in the next line. Thus you can use this to move through a paragraph, much faster than using "l". "b" does the same in the other direction. A word ends at a non-word character, such as a ".", "-" or ")". To change what Vim considers to be a word, see the 'iskeyword' option. It is also possible to move by white-space separated WORDs. This is not a word in the normal sense, that's why the uppercase is used. The commands for moving by WORDs are also uppercase, as this figure shows: ge b w e <- <- ---> ---> This is-a line, with special/separated/words (and some more). ~ <----- <----- --------------------> -----> gE B W E With this mix of lowercase and uppercase commands, you can quickly move forward and backward through a paragraph. ============================================================================== *03.2* Moving to the start or end of a line The "$" command moves the cursor to the end of a line. If your keyboard has an <End> key it will do the same thing. The "^" command moves to the first nonblank character of the line. The "0" command (zero) moves to the very first character of the line. The <Home> key does the same thing. In a picture: ^ <------------ .....This is a line with example text ~ <----------------- ---------------> 0 $ (the "....." indicates blanks here) The "$" command takes a count, like most movement commands. But moving to the end of the line several times doesn't make sense. Therefore it causes the editor to move to the end of another line. For example, "1$" moves you to the end of the first line (the one you're on), "2$" to the end of the next line, and so on. The "0" command doesn't take a count argument, because the "0" would be part of the count. Unexpectedly, using a count with "^" doesn't have any effect. ============================================================================== *03.3* Moving to a character One of the most useful movement commands is the single-character search command. The command "fx" searches forward in the line for the single character x. Hint: "f" stands for "Find". For example, you are at the beginning of the following line. Suppose you want to go to the h of human. Just execute the command "fh" and the cursor will be positioned over the h: To err is human. To really foul up you need a computer. ~ ---------->---------------> fh fy This also shows that the command "fy" moves to the end of the word really. You can specify a count; therefore, you can go to the "l" of "foul" with "3fl": To err is human. To really foul up you need a computer. ~ ---------------------> 3fl The "F" command searches to the left: To err is human. To really foul up you need a computer. ~ <--------------------- Fh The "tx" command works like the "fx" command, except it stops one character before the searched character. Hint: "t" stands for "To". The backward version of this command is "Tx". To err is human. To really foul up you need a computer. ~ <------------ -------------> Th tn These four commands can be repeated with ";". "," repeats in the other direction. The cursor is never moved to another line. Not even when the sentence continues. Sometimes you will start a search, only to realize that you have typed the wrong command. You type "f" to search backward, for example, only to realize that you really meant "F". To abort a search, press <Esc>. So "f<Esc>" is an aborted forward search and doesn't do anything. Note: <Esc> cancels most operations, not just searches. ============================================================================== *03.4* Matching a paren When writing a program you often end up with nested () constructs. Then the "%" command is very handy: It moves to the matching paren. If the cursor is on a "(" it will move to the matching ")". If it's on a ")" it will move to the matching "(". % <-----> if (a == (b * c) / d) ~ <----------------> % This also works for [] and {} pairs. (This can be defined with the 'matchpairs' option.) When the cursor is not on a useful character, "%" will search forward to find one. Thus if the cursor is at the start of the line of the previous example, "%" will search forward and find the first "(". Then it moves to its match: if (a == (b * c) / d) ~ ---+----------------> % ============================================================================== *03.5* Moving to a specific line If you are a C or C++ programmer, you are familiar with error messages such as the following: prog.c:33: j undeclared (first use in this function) ~ This tells you that you might want to fix something on line 33. So how do you find line 33? One way is to do "9999k" to go to the top of the file and "32j" to go down thirtytwo lines. It is not a good way, but it works. A much better way of doing things is to use the "G" command. With a count, this command positions you at the given line number. For example, "33G" puts you on line 33. (For a better way of going through a compiler's error list, see |usr_30.txt|, for information on the :make command.) With no argument, "G" positions you at the end of the file. A quick way to go to the start of a file use "gg". "1G" will do the same, but is a tiny bit more typing. | first line of a file ^ | text text text text | | text text text text | gg 7G | text text text text | | text text text text | text text text text V text text text text | text text text text | G text text text text | last line of a file V Another way to move to a line is using the "%" command with a count. For example "50%" moves you to halfway the file. "90%" goes to near the end. The previous assumes that you want to move to a line in the file, no matter if it's currently visible or not. What if you want to move to one of the lines you can see? This figure shows the three commands you can use: +---------------------------+ H --> | text sample text | | sample text | | text sample text | | sample text | M --> | text sample text | | sample text | | text sample text | | sample text | L --> | text sample text | +---------------------------+ Hints: "H" stands for Home, "M" for Middle and "L" for Last. ============================================================================== *03.6* Telling where you are To see where you are in a file, there are three ways: 1. Use the CTRL-G command. You get a message like this (assuming the 'ruler' option is off): "usr_03.txt" line 233 of 650 --35%-- col 45-52~ This shows the name of the file you are editing, the line number where the cursor is, the total number of lines, the percentage of the way through the file and the column of the cursor. Sometimes you will see a split column number. For example, "col 2-9". This indicates that the cursor is positioned on the second character, but because character one is a tab, occupying eight spaces worth of columns, the screen column is 9. 2. Set the 'number' option. This will display a line number in front of every line: > :set number < To switch this off again: > :set nonumber < Since 'number' is a boolean option, prepending "no" to its name has the effect of switching it off. A boolean option has only these two values, it is either on or off. Vim has many options. Besides the boolean ones there are options with a numerical value and string options. You will see examples of this where they are used. 3. Set the 'ruler' option. This will display the cursor position in the lower right corner of the Vim window: > :set ruler Using the 'ruler' option has the advantage that it doesn't take much room, thus there is more space for your text. ============================================================================== *03.7* Scrolling around The CTRL-U command scrolls down half a screen of text. Think of looking through a viewing window at the text and moving this window up by half the height of the window. Thus the window moves up over the text, which is backward in the file. Don't worry if you have a little trouble remembering which end is up. Most users have the same problem. The CTRL-D command moves the viewing window down half a screen in the file, thus scrolls the text up half a screen. +----------------+ | some text | | some text | | some text | +---------------+ | some text | | some text | CTRL-U --> | | | | | 123456 | | 123456 | +----------------+ | 7890 | | | +----------------+ | example | CTRL-D --> | 7890 | +---------------+ | | | example | | example | | example | | example | +----------------+ To scroll one line at a time use CTRL-E (scroll up) and CTRL-Y (scroll down). Think of CTRL-E to give you one line Extra. (If you use MS-Windows compatible key mappings CTRL-Y will redo a change instead of scroll.) To scroll forward by a whole screen (except for two lines) use CTRL-F. The other way is backward, CTRL-B is the command to use. Fortunately CTRL-F is Forward and CTRL-B is Backward, that's easy to remember. A common issue is that after moving down many lines with "j" your cursor is at the bottom of the screen. You would like to see the context of the line with the cursor. That's done with the "zz" command. +------------------+ +------------------+ | some text | | some text | | some text | | some text | | some text | | some text | | some text | zz --> | line with cursor | | some text | | some text | | some text | | some text | | line with cursor | | some text | +------------------+ +------------------+ The "zt" command puts the cursor line at the top, "zb" at the bottom. There are a few more scrolling commands, see |Q_sc|. To always keep a few lines of context around the cursor, use the 'scrolloff' option. ============================================================================== *03.8* Simple searches To search for a string, use the "/string" command. To find the word include, for example, use the command: > /include You will notice that when you type the "/" the cursor jumps to the last line of the Vim window, like with colon commands. That is where you type the word. You can press the backspace key (backarrow or <BS>) to make corrections. Use the <Left> and <Right> cursor keys when necessary. Pressing <Enter> executes the command. Note: The characters .*[]^%/\?~$ have special meaning. If you want to use them in a search you must put a \ in front of them. See below. To find the next occurrence of the same string use the "n" command. Use this to find the first #include after the cursor: > /#include And then type "n" several times. You will move to each #include in the text. You can also use a count if you know which match you want. Thus "3n" finds the third match. Using a count with "/" doesn't work. The "?" command works like "/" but searches backwards: > ?word The "N" command repeats the last search the opposite direction. Thus using "N" after a "/" command search backwards, using "N" after "?" searches forward. IGNORING CASE Normally you have to type exactly what you want to find. If you don't care about upper or lowercase in a word, set the 'ignorecase' option: > :set ignorecase If you now search for "word", it will also match "Word" and "WORD". To match case again: > :set noignorecase HISTORY Suppose you do three searches: > /one /two /three Now let's start searching by typing a simple "/" without pressing <Enter>. If you press <Up> (the cursor key), Vim puts "/three" on the command line. Pressing <Enter> at this point searches for three. If you do not press <Enter>, but press <Up> instead, Vim changes the prompt to "/two". Another press of <Up> moves you to "/one". You can also use the <Down> cursor key to move through the history of search commands in the other direction. If you know what a previously used pattern starts with, and you want to use it again, type that character before pressing <Up>. With the previous example, you can type "/o<Up>" and Vim will put "/one" on the command line. The commands starting with ":" also have a history. That allows you to recall a previous command and execute it again. These two histories are separate. SEARCHING FOR A WORD IN THE TEXT Suppose you see the word "TheLongFunctionName" in the text and you want to find the next occurrence of it. You could type "/TheLongFunctionName", but that's a lot of typing. And when you make a mistake Vim won't find it. There is an easier way: Position the cursor on the word and use the "*" command. Vim will grab the word under the cursor and use it as the search string. The "#" command does the same in the other direction. You can prepend a count: "3*" searches for the third occurrence of the word under the cursor. SEARCHING FOR WHOLE WORDS If you type "/the" it will also match "there". To only find words that end in "the" use: > /the\> The "\>" item is a special marker that only matches at the end of a word. Similarly "\<" only matches at the begin of a word. Thus to search for the word "the" only: > /\<the\> This does not match "there" or "soothe". Notice that the "*" and "#" commands use these start-of-word and end-of-word markers to only find whole words (you can use "g*" and "g#" to match partial words). HIGHLIGHTING MATCHES While editing a program you see a variable called "nr". You want to check where it's used. You could move the cursor to "nr" and use the "*" command and press "n" to go along all the matches. There is another way. Type this command: > :set hlsearch If you now search for "nr", Vim will highlight all matches. That is a very good way to see where the variable is used, without the need to type commands. To switch this off: > :set nohlsearch Then you need to switch it on again if you want to use it for the next search command. If you only want to remove the highlighting, use this command: > :nohlsearch This doesn't reset the option. Instead, it disables the highlighting. As soon as you execute a search command, the highlighting will be used again. Also for the "n" and "N" commands. TUNING SEARCHES There are a few options that change how searching works. These are the essential ones: > :set incsearch This makes Vim display the match for the string while you are still typing it. Use this to check if the right match will be found. Then press <Enter> to really jump to that location. Or type more to change the search string. > :set nowrapscan This stops the search at the end of the file. Or, when you are searching backwards, at the start of the file. The 'wrapscan' option is on by default, thus searching wraps around the end of the file. INTERMEZZO If you like one of the options mentioned before, and set it each time you use Vim, you can put the command in your Vim startup file. Edit the file, as mentioned at |not-compatible|. Or use this command to find out where it is: > :scriptnames Edit the file, for example with: > :edit ~/.vimrc Then add a line with the command to set the option, just like you typed it in Vim. Example: > Go:set hlsearch<Esc> "G" moves to the end of the file. "o" starts a new line, where you type the ":set" command. You end insert mode with <Esc>. Then write the file: > ZZ If you now start Vim again, the 'hlsearch' option will already be set. ============================================================================== *03.9* Simple search patterns The Vim editor uses regular expressions to specify what to search for. Regular expressions are an extremely powerful and compact way to specify a search pattern. Unfortunately, this power comes at a price, because regular expressions are a bit tricky to specify. In this section we mention only a few essential ones. More about search patterns and commands in chapter 27 |usr_27.txt|. You can find the full explanation here: |pattern|. BEGINNING AND END OF A LINE The ^ character matches the beginning of a line. On an English-US keyboard you find it above the 6. The pattern "include" matches the word include anywhere on the line. But the pattern "^include" matches the word include only if it is at the beginning of a line. The $ character matches the end of a line. Therefore, "was$" matches the word was only if it is at the end of a line. Let's mark the places where "the" matches in this example line with "x"s: the solder holding one of the chips melted and the ~ xxx xxx xxx Using "/the$" we find this match: the solder holding one of the chips melted and the ~ xxx And with "/^the" we find this one: the solder holding one of the chips melted and the ~ xxx You can try searching with "/^the$", it will only match a single line consisting of "the". White space does matter here, thus if a line contains a space after the word, like "the ", the pattern will not match. MATCHING ANY SINGLE CHARACTER The . (dot) character matches any existing character. For example, the pattern "c.m" matches a string whose first character is a c, whose second character is anything, and whose the third character is m. Example: We use a computer that became the cummin winter. ~ xxx xxx xxx MATCHING SPECIAL CHARACTERS If you really want to match a dot, you must avoid its special meaning by putting a backslash before it. If you search for "ter.", you will find these matches: We use a computer that became the cummin winter. ~ xxxx xxxx Searching for "ter\." only finds the second match. ============================================================================== *03.10* Using marks When you make a jump to a position with the "G" command, Vim remembers the position from before this jump. This position is called a mark. To go back where you came from, use this command: > `` This ` is a backtick or open single-quote character. If you use the same command a second time you will jump back again. That's because the ` command is a jump itself, and the position from before this jump is remembered. Generally, every time you do a command that can move the cursor further than within the same line, this is called a jump. This includes the search commands "/" and "n" (it doesn't matter how far away the match is). But not the character searches with "fx" and "tx" or the word movements "w" and "e". Also, "j" and "k" are not considered to be a jump. Even when you use a count to make them move the cursor quite a long way away. The `` command jumps back and forth, between two points. The CTRL-O command jumps to older positions (Hint: O for older). CTRL-I then jumps back to newer positions (Hint: I is just next to O on the keyboard). Consider this sequence of commands: > 33G /^The CTRL-O You first jump to line 33, then search for a line that starts with "The". Then with CTRL-O you jump back to line 33. Another CTRL-O takes you back to where you started. If you now use CTRL-I you jump to line 33 again. And to the match for "The" with another CTRL-I. | example text ^ | 33G | example text | CTRL-O | CTRL-I | example text | | V line 33 text ^ V | example text | | /^The | example text | CTRL-O | CTRL-I V There you are | V example text Note: CTRL-I is the same as <Tab>. The ":jumps" command gives a list of positions you jumped to. The entry which you used last is marked with a ">". NAMED MARKS Vim enables you to place your own marks in the text. The command "ma" marks the place under the cursor as mark a. You can place 26 marks (a through z) in your text. You can't see them, it's just a position that Vim remembers. To go to a mark, use the command `{mark}, where "{mark} is the mark letter. Thus to move to the a mark: > `a The command 'mark (single quotation mark, or apostrophe) moves you to the beginning of the line containing the mark. This differs from the `mark command, which moves you to marked column. The marks can be very useful when working on two related parts in a file. Suppose you have some text near the start of the file you need to look at, while working on some text near the end of the file. Move to the text at the start and place the s (start) mark there: > ms The move to the text you want to work on and put the e (end) mark there: > me Now you can move around, and when you want to look at the start of the file, you use this to jump there: > 's Then you can use '' to jump back to where you were, or 'e to jump to the text you were working on at the end. There is nothing special about using s for start and e for end, they are just easy to remember. You can use this command to get a list of marks: > :marks You will notice a few special marks. These include: ' The cursor position before doing a jump " The cursor position when last editing the file [ Start of the last change ] End of the last change ============================================================================== *usr_04.txt* For Vim version 6.1. Last change: 2002 Jan 07 Making small changes This chapter shows you several ways of making corrections and moving text around. It teaches you the three basic ways to change text: operator-motion, Visual mode and text objects. |04.1| Operators and motions |04.2| Changing text |04.3| Repeating a change |04.4| Visual mode |04.5| Moving text |04.6| Copying text |04.7| Using the clipboard |04.8| Text objects |04.9| Replace mode |04.10| Conclusion ============================================================================== *04.1* Operators and motions In chapter 2 you learned the "x" command to delete a single character. And using a count: "4x" deletes four characters. The "dw" command deletes a word. You may recognize the "w" command as the move word command. In fact, the "d" command may be followed by any motion command, and it deletes from the current location to the place where the cursor winds up. The "4w" command, for example, moves the cursor over four words. The d4w command deletes four words. To err is human. To really foul up you need a computer. ~ ------------------> d4w To err is human. you need a computer. ~ Vim only deletes up to the position where the motion takes the cursor. That's because Vim knows that you probably don't want to delete the first character of a word. If you use the "e" command to move to the end of a word, Vim guesses that you do want to include that last character: To err is human. you need a computer. ~ --------> d2e To err is human. a computer. ~ Whether the character under the cursor is included depends on the command you used to move to that character. The reference manual calls this "exclusive" when the character isn't included and "inclusive" when it is. The "$" command moves to the end of a line. The "d$" command deletes from the cursor to the end of the line. This is an inclusive motion, thus the last character of the line is included in the delete operation: To err is human. a computer. ~ ------------> d$ To err is human ~ There is a pattern here: operator-motion. You first type an operator command. For example, "d" is the delete operator. Then you type a motion command like "4l" or "w". This way you can operate on any text you can move over. ============================================================================== *04.2* Changing text Another operator is "c", change. It acts just like the "d" operator, except it leaves you in Insert mode. For example, "cw" changes a word. Or more specifically, it deletes a word and then puts you in Insert mode. To err is human ~ -------> c2wbe<Esc> To be human ~ This "c2wbe<Esc>" contains these bits: c the change operator 2w move two words (they are deleted and Insert mode started) be insert this text <Esc> back to Normal mode If you have paid attention, you will have noticed something strange: The space before "human" isn't deleted. There is a saying that for every problem there is an answer that is simple, clear, and wrong. That is the case with the example used here for the "cw" command. The c operator works just like the d operator, with one exception: "cw". It actually works like "ce", change to end of word. Thus the space after the word isn't included. This is an exception that dates back to the old Vi. Since many people are used to it now, the inconsistency has remained in Vim. MORE CHANGES Like "dd" deletes a whole line, "cc" changes a whole line. It keeps the existing indent (leading white space) though. Just like "d$" deletes until the end of the line, "c$" changes until the end of the line. It's like doing "d$" to delete the text and then "a" to start Insert mode and append new text. SHORTCUTS Some operator-motion commands are used so often that they have been given a single letter command: x stands for dl (delete character under the cursor) X stands for dh (delete character left of the cursor) D stands for d$ (delete to end of the line) C stands for c$ (change to end of the line) s stands for cl (change one character) S stands for cc (change a whole line) WHERE TO PUT THE COUNT The commands "3dw" and "d3w" delete three words. If you want to get really picky about things, the first command, "3dw", deletes one word three times; the command "d3w" deletes three words once. This is a difference without a distinction. You can actually put in two counts, however. For example, "3d2w" deletes two words, repeated three times, for a total of six words. REPLACING WITH ONE CHARACTER The "r" command is not an operator. It waits for you to type a character, and will replace the character under the cursor with it. You could do the same with "cl" or with the "s" command, but with "r" you don't have to press <Esc> there is somerhing grong here ~ rT rt rw There is something wrong here ~ Using a count with "r" causes that many characters to be replaced with the same character. Example: There is something wrong here ~ 5rx There is something xxxxx here ~ To replace a character with a line break use "r<Enter>". This deletes one character and inserts a line break. Using a count here only applies to the number of characters deleted: "4r<Enter>" replaces four characters with one line break. ============================================================================== *04.3* Repeating a change The "." command is one of the most simple yet powerful commands in Vim. It repeats the last change. For instance, suppose you are editing an HTML file and want to delete all the <B> tags. You position the cursor on the first < and delete the <B> with the command "df>". You then go to the < of the next </B> and kill it using the "." command. The "." command executes the last change command (in this case, "df>"). To delete another tag, position the cursor on the < and use the "." command. To <B>generate</B> a table of <B>contents ~ f< find first < ---> df> delete to > --> f< find next < ---------> . repeat df> ---> f< find next < -------------> . repeat df> --> The "." command works for all changes you make, except for the "u" (undo), CTRL-R (redo) and commands that st