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:<PHONE_NUMBER>). 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.  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".  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 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.  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>".  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 start with a colon (:). Another example: You want to change the word "four" to "five". It appears several times in your text. You can do this quickly with this sequence of commands: /four<Enter> find the first string "four" cwfive<Esc> change the word to "five" n find the next "four" . repeat the change to "five' n find the next "four" . repeat the change etc.
*04.4* Visual mode To delete simple items the operator-motion changes work quite well. But often it's not so easy to decide which command will move over the text you want to change. Then you can use Visual mode. You start Visual mode by pressing "v". You move the cursor over the text you want to work on. While you do this, the text is highlighted. Finally type the operator command. For example, to delete from halfway one word to halfway another word: This is an examination sample of visual mode ~ ----------> velllld This is an example of visual mode ~ When doing this you don't really have to count how many times you have to press "l" to end up in the right position. You can immediately see what text will be deleted when you press "d". If at any time you decide you don't want to do anything with the highlighted text, just press <Esc> and Visual mode will stop without doing anything. SELECTING LINES If you want to work on whole lines, use "V" to start Visual mode. You will see right away that the whole line is highlighted, without moving around. When you move left or right nothing changes. When you move up or down the selection is extended whole lines at a time. For example, select three lines with "Vjj": +------------------------+ | text more text | >> | more text more text | | selected lines >> | text text text | | Vjj >> | text more | V | more text more | +------------------------+ SELECTING BLOCKS If you want to work on a rectangular block of characters, use CTRL-V to start Visual mode. This is very useful when working on tables. name Q1 Q2 Q3 pierre 123 455 234 john 0 90 39 steve 392 63 334 To delete the middle "Q2" column, move the cursor to the "Q" of "Q2". Press CTRL-V to start blockwise Visual mode. Now move the cursor three lines down with "3j" and to the next word with "w". You can see the first character of the last column is included. To exclude it, use "h". Now press "d" and the middle column is gone. GOING TO THE OTHER SIDE If you have selected some text in Visual mode, and discover that you need to change the other end of the selection, use the "o" command (Hint: o for other end). The cursor will go to the other end, and you can move the cursor to change where the selection starts. Pressing "o" again brings you back to the other end. When using blockwise selection, you have four corners. "o" only takes you to one of the other corners, diagonally. Use "O" to move to the other corner in the same line. Note that "o" and "O" in Visual mode work very different from Normal mode, where they open a new line below or above the cursor.
*04.5* Moving text When you delete something with the "d", "x", or another command, the text is saved. You can paste it back by using the p command. (The Vim name for this is put). Take a look at how this works. First you will delete an entire line, by putting the cursor on the line you want to delete and typing "dd". Now you move the cursor to where you want to put the line and use the "p" (put) command. The line is inserted on the line below the cursor. a line a line a line line 2 dd line 3 p line 3 line 3 line 2 Because you deleted an entire line, the "p" command placed the text line below the cursor. If you delete part of a line (a word, for instance), the "p" command puts it just after the cursor.  When you deleted a whole line with "dd", "P" will put it back above the cursor. When you deleted a word with "dw", "P" will put it back just before the cursor. You can repeat putting as many times as you like. The same text will be used. You can use a count with "p" and "P". The text will be repeated as many times as specified with the count. Thus "dd" and then "3p" puts three copies of the same deleted line. SWAPPING TWO CHARACTERS Frequently when you are typing, your fingers get ahead of your brain (or the other way around?). The result is a typo such as "teh" for "the". Vim makes it easy to correct such problems. Just put the cursor on the e of "teh" and execute the command "xp". This works as follows: "x" deletes the character e and places it in a register. "p" puts the text after the cursor, which is after the h. teh th the~ x p
*04.6* Copying text To copy text from one place to another, you could delete it, use "u" to undo the deletion and then "p" to put it somewhere else. There is an easier way: yanking. The "y" operator copies text into a register. Then a "p" command can be used to put it. Yanking is just a Vim name for copying. The "c" letter was already used for the change operator, and "y" was still available. Calling this operator "yank" made it easier to remember to use the "y" key. Since "y" is an operator, you use "yw" to yank a word. A count is possible as usual. To yank two workds use "y2w". Example: let sqr = LongVariable * ~ --------------> y2w let sqr = LongVariable * ~ p let sqr = LongVariable * LongVariable ~ Notice that "yw" includes the white space after a word. If you don't want this, use "ye". The "yy" command yanks a whole line, just like "dd" deletes a whole line. Unexpectedly, while "D" deletes from the cursor to the end of the line, "Y" works like "yy", it yanks the whole line. Watch out for this inconsistency!  First select some text with Visual mode, then use the Edit/Copy menu. The selected text is now copied to the clipboard. You can paste the text in other programs. In Vim itself too. If you have copied text to the clipboard in another application, you can paste it in Vim with the Edit/Paste menu. This works in Normal mode and Insert mode. In Visual mode the selected text is replaced with the pasted text. The "Cut" menu item deletes the text before it's put on the clipboard. The "Copy", "Cut" and "Paste" items are also available in the popup menu (only when there is a popup menu, of course). If your Vim has a toolbar, you can also find these items there. If you are not using the GUI, or if you don't like using a menu, you have to use another way. You use the normal "y" (yank) and "p" (put) commands, but prepend "* (double-quote star) before it. To copy a line to the clipboard: > "*yy To put text from the clipboard back into the text: > "*p This only works on versions of Vim that include clipboard support. More about the clipboard in section |09.3| and here: |clipboard|.
*04.8* Text objects If the cursor is in the middle of a word and want to delete that word, you need to move back to its start before you can do "dw". There is a simpler way to do this: "daw". this is some example text. ~ daw this is some text. ~ The "d" of "daw" is the delete operator. "aw" is a text object. Hint: "aw" stands for "A Word". Thus "daw" is "Delete A Word". Using text objects is the third way to make changes in Vim. We already had operator-motion and Visual mode. Now we add operator-text object. It is very similar to operator-motion, but instead of operating on the text between the cursor position before and after a movement command, the text object is used as a whole. It doesn't matter where in the object the cursor was. To change a whole sentence use "cis". Take this text: Hello there. This ~ is an example. Just ~ some text. ~ Move to the start of the second line, on "is an". Now use "cis": Hello there. Just ~ some text. ~ The cursor is in between the blanks in the first line. Now you type the new sentence "Another line.": Hello there. Another line. Just ~ some text. ~ "cis" consists of the "c" (change) operator and the "is" text object. This stands for "Inner Sentence". There is also the "as" (a sentence) object. The difference is that "as" includes the white space after the sentence and "is" doesn't. If you would delete a sentence, you want to delete the white space at the same time, thus use "das". If you want to type new text the white space can remain, thus you use "cis". You can also use text objects in Visual mode. It will include the text object in the Visual selection. Visual mode continues, thus you can do this several times. For example, start Visual mode with "v" and select a sentence with "as". Now you can repeat "as" to include more sentences. Finally you use an operator to do something with the selected sentences. You can find a long list of text objects here: |text-objects|.
*04.9* Replace mode The "R" command causes Vim to enter replace mode. In this mode, each character you type replaces the one under the cursor. This continues until you type <Esc>. In this example you start Replace mode on the first "t" of "text": This is text. ~ Rinteresting.<Esc> This is interesting. ~ You may have noticed that this command replaced 5 characters in the line with twelve others. The "R" command automatically extends the line if it runs out of characters to replace. It will not continue on the next line. You can switch between Insert mode and Replace mode with the <Insert> key. When you use <BS> (backspace) to make correction, you will notice that the old text is put back. Thus it works like an undo command for the last typed character.
*04.10* Conclusion The operators, movement commands and text objects give you the possibility to make lots of combinations. Now that you know how it works, you can use N operators with M movement commands to make N * M commands! You can find a list of operators here: |operator| For example, there are many other ways to delete pieces of text. Here are a few often used ones: x delete character under the cursor (short for "dl") X delete character before the cursor (short for "dh") D delete from cursor to end of line (short for "d$") dw delete from cursor to next start of word db delete from cursor to previous start of word diw delete word under the cursor (excluding white space) daw delete word under the cursor (including white space) dG delete until the end of the file dgg delete until the start of the file If you use "c" instead of "d" they become change commands. And with "y" you yank the text. And so forth. There are a few often used commands to make changes that didn't fit somewhere else: ~ change case of the character under the cursor, and move the cursor to the next character. This is not an operator (unless 'tildeop' is set), thus you can't use it with a motion command. It does works in Visual mode and changes case for all the selected text then. I Start Insert mode after moving the cursor to the first non-blank in the line. A Start Insert mode after moving the cursor to the end of the line.
*usr_05.txt* For Vim version 6.1. Last change: 2001 Nov 02 Set your settings Vim can be tuned to work like you want it to. This chapter shows you how to make Vim start with options set to different values. Add plugins to extend Vims capabilities. Or define your own macros. |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
*05.1* The vimrc file You probably got tired of typing commands that you use very often. To start with all your favorite option settings and mappings, you write them in what is called the vimrc file. Vim reads this file when it starts up. If you have trouble finding your vimrc file, use this command: > :scriptnames One of the first files in the list should be called ".vimrc" or "_vimrc" and is located in your home directory. If you don't have a vimrc file yet, see |vimrc| to find out where you can create a vimrc file. Also, the ":version" command mentions the name of the "user vimrc file" Vim looks for. For Unix this file is always used: > ~/.vimrc For MS-DOS and MS-Windows it is mostly one of these: > $HOME/_vimrc $VIM/_vimrc The vimrc file can contain all the commands that you type after a colon. The most simple ones are for setting options. For example, if you want Vim to always start with the 'incsearch' option on, add this line you your vimrc file: > set incsearch For this new line to take effect you need to exit Vim and start it again. Later you will learn how to do this without exiting Vim. This chapter only explains the most basic items. For more information on how to write a Vim script file: |usr_41.txt|.
*05.2* The example vimrc file explained *vimrc_example.vim* In the first chapter was explained how the example vimrc (included in the Vim distribution) file can be used to make Vim startup in not-compatible mode (see |not-compatible|). The file can be found here: $VIMRUNTIME/vimrc_example.vim ~ In this section we will explain the various commands used in this file. This will give you hints about how to set up your own preferences. Not everything will be explained though. Use the ":help" command to find out more. > set nocompatible As mentioned in the first chapter, these manuals explain Vim working in an improved way, thus not completely Vi compatible. Setting the 'compatible' option off, thus 'nocompatible' takes care of this. > set backspace=indent,eol,start This specifies where in Insert mode the <BS> is allowed to delete the character in front of the cursor. The three items, separated by commas, tell Vim to delete the white space at the start of the line, a line break and the character before where Insert mode started. > set autoindent This makes Vim use the indent of the previous line for a newly created line. Thus there is the same amount of white space before the new line. For example when pressing <Enter> in Insert mode, and when using the "o" command to open a new line. > if has("vms") set nobackup else set backup endif This tells Vim to keep a backup copy of a file when overwriting it. But not on the VMS system, since it keeps old versions of files already. The backup file will have the same name as the original file with "~" added. See |07.4| > set history=50 Keep 50 commands and 50 search patterns in the history. Use another number if you want to remember fewer or more lines. > set ruler Always display the current cursor position in the lower right corner of the Vim window. > set showcmd Display an incomplete command in the lower right corner of the Vim window, left of the ruler. For example, when you type "2f", Vim is waiting for you to type the character to find and "2f" is displayed. When you press "w" next, the "2fw" command is executed and the displayed "2f" is removed. +-------------------------------------------------+ |text in the Vim window | |~ | |~ | |-- VISUAL -- 2f 43,8 17% | +-------------------------------------------------+ ^^^^^^^^^^^ ^^^^^^^^ ^^^^^^^^^^ 'showmode' 'showcmd' 'ruler' > set incsearch Display the match for a search pattern when halfway typing it. > map Q gq This defines a key mapping. More about that in the next section. This defines the "Q" command to do formatting with the "gq" operator. This is how it worked before Vim 5.0. Otherwise the "Q" command starts Ex mode, but you will not need it. > vnoremap p <Esc>:let current_reg = @"<CR>gvs<C-R>=current_reg<CR><Esc> This is a complicated mapping. It will not be explained how it works here. What it does is to make "p" in Visual mode overwrite the selected text with the previously yanked text. You can see that mappings can be used to do quite complicated things. Still, it is just a sequence of commands that are executed like you typed them. > if &t_Co > 2 || has("gui_running") syntax on set hlsearch endif This switches on syntax highlighting, but only if colors are available. And the 'hlsearch' option tells Vim to highlight matches with the last used search pattern. The "if" command is very useful to set options only when some condition is met. More about that in |usr_41.txt|. *vimrc-filetype* > filetype plugin indent on This switches on three very clever mechanisms: 1. Filetype detection. Whenever you start editing a file, Vim will try to figure out what kind of file this is. When you edit "main.c", Vim will see the ".c" extension and recognize this as a "c" filetype. When you edit a file that starts with "#!/bin/sh", Vim will recognize it as a "sh" filetype. The filetype detection is used for syntax highlighting and the other two items below. See |filetypes|. 2. Using filetype plugin files Many different filetypes are edited with different options. For example, when you edit a "c" file, it's very useful to set the 'cindent' option to automatically indent the lines. These commonly useful option settings are included with Vim in filetype plugins. You can also add your own, see |write-filetype-plugin|. 3. Using indent files When editing programs, the indent of a line can often be computed automatically. Vim comes with these indent rules for a number of filetypes. See |:filetype-indent-on| and 'indentexpr'. > autocmd FileType text setlocal textwidth=78 This makes Vim break text to avoid lines getting longer than 78 characters. But only for files that have been detected to be plain text. There are actually two parts here. "autocmd FileType text" is an autocommand. This defines that when the file type is set to "text" the following command is automatically executed. "setlocal textwidth=78" sets the 'textwidth' option to 78, but only locally in one file. > autocmd BufReadPost * \ if line("'\"") > 0 && line("'\"") <= line("$") | \ exe "normal g`\"" | \ endif Another autocommand. This time it is used after reading any file. The complicated stuff after it checks if the '" mark is defined, and jumps to it if so. The backslash at the start of a line is used to continue the command from the previous line. That avoids a line getting very long. See |line-continuation|. This only works in a Vim script file, not when typing commands at the command-line.
*05.3* Simple mappings A mapping enables you to bind a set of Vim commands to a single key. Suppose, for example, that you need to surround certain words with curly braces. In other words, you need to change a word such as "amount" into "{amount}". With the :map command, you can tell Vim that the F5 key does this job. The command is as follows: > :map <F5> i{<Esc>ea}<Esc> < Note: When entering this command, you must enter <F5> by typing four characters. Similarly, <Esc> is not entered by pressing the <Esc> key, but by typing five characters. Watch out for this difference when reading the manual! Let's break this down: <F5> The F5 function key. This is the trigger key that causes the command to be executed as the key is pressed. i{<Esc> Insert the { character. The <Esc> key ends Insert mode. e Move to the end of the word. a}<Esc> Append the } to the word. After you execute the ":map" command, all you have to do to put {} around a word is to put the cursor on the first character and press F5. In this example, the trigger is a single key; it can be any string. But when you use an existing Vim command, that command will no longer be available. You better avoid that. One key that can be used with mappings is the backslash. Since you probably want to define more than one mapping, add another character. You could map "\p" to add parens around a word, and "\c" to add curly braces, for example: > :map \p i(<Esc>ea)<Esc> :map \c i{<Esc>ea}<Esc> You need to type the \ and the p quickly after another, so that Vim knows they belong together. The ":map" command (with no arguments) lists your current mappings. At least the ones for Normal mode. More about mappings in section |40.1|.
*05.4* Adding a plugin *add-plugin* *plugin* Vim's functionality can be extended by adding plugins. A plugin is nothing more than a Vim script file that is loaded automatically when Vim starts. You can add a plugin very easily by dropping it in your plugin directory. {not available when Vim was compiled without the |+eval| feature} There are two types of plugins: global plugin: Used for all kinds of files filetype plugin: Only used for a specific type of file The global plugins will be discussed first, then the filetype ones |add-filetype-plugin|. GLOBAL PLUGINS *standard-plugin* When you start Vim, it will automatically load a number of global plugins. You don't have to do anything for this. They add functionality that most people will want to use, but which was implemented as a Vim script instead of being compiled into Vim. You can find them listed in the help index |standard-plugin-list|. Also see |load-plugins|. *add-global-plugin* You can add a global plugin to add functionality that will always be present when you use Vim. There are only two steps for adding a global plugin: 1. Get a copy of the plugin. 2. Drop it in the right directory. GETTING A GLOBAL PLUGIN Where can you find plugins? - Some come with Vim. You can find them in the directory $VIMRUNTIME/macros and its sub-directories. - Download from the net, check out http://vim.sf.net. - They are sometimes posted in a Vim |maillist|. - You could write one yourself, see |write-plugin|. USING A GLOBAL PLUGIN First read the text in the plugin itself to check for any special conditions. Then copy the file to your plugin directory: system plugin directory ~ Unix ~/.vim/plugin/ PC and OS/2 $HOME/vimfiles/plugin or $VIM/vimfiles/plugin Amiga s:vimfiles/plugin Macintosh $VIM:vimfiles:plugin RISC-OS Choices:vimfiles.plugin Example for Unix (assuming you didn't have a plugin directory yet): > mkdir ~/.vim mkdir ~/.vim/plugin cp /usr/local/share/vim/vim60/macros/justify.vim ~/.vim/plugin That's all! Now you can use the commands defined in this plugin to justify text. FILETYPE PLUGINS *add-filetype-plugin* *ftplugins* The Vim distribution comes with a set of plugins for different filetypes that you can start using with this command: > :filetype plugin on That's all! See |vimrc-filetype|. If you are missing a plugin for a filetype you are using, or you found a better one, you can add it. There are two steps for adding a filetype plugin: 1. Get a copy of the plugin. 2. Drop it in the right directory. GETTING A FILETYPE PLUGIN You can find them in the same places as the global plugins. Watch out if the type of file is mentioned, then you know if the plugin is a global or a filetype one. The scripts in $VIMRUNTIME/macros are global ones, the filetype plugins are in $VIMRUNTIME/ftplugin. USING A FILETYPE PLUGIN You can add a filetype plugin by dropping it in the right directory. The name of this directory is in the same directory mentioned above for global plugins, but the last part is "ftplugin". Suppose you have found a plugin for the "stuff" filetype, and you are on Unix. Then you can move this file to the ftplugin directory: > mv thefile ~/.vim/ftplugin/stuff.vim If that file already exists you already have a plugin for "stuff". You might want to check if the existing plugin doesn't conflict with the one you are adding. If it's OK, you can give the new one another name: > mv thefile ~/.vim/ftplugin/stuff_too.vim The underscore is used to separate the name of the filetype from the rest, which can be anything. If you would use "otherstuff.vim" it wouldn't work, it would be loaded for the "otherstuff" filetype. On MS-DOS you cannot use long filenames. You would run into trouble if you add a second plugin and the filetype has more than six characters. You can use an extra directory to get around this: > mkdir $VIM/vimfiles/ftplugin/fortran copy thefile $VIM/vimfiles/ftplugin/fortran/too.vim The generic names for the filetype plugins are: > ftplugin/<filetype>.vim ftplugin/<filetype>_<name>.vim ftplugin/<filetype>/<name>.vim Here "<name>" can be any name that you prefer. Examples for the "stuff" filetype on Unix: > ~/.vim/ftplugin/stuff.vim ~/.vim/ftplugin/stuff_def.vim ~/.vim/ftplugin/stuff/header.vim The <filetype> part is the name of the filetype the plugin is to be used for. Only files of this filetype will use the settings from the plugin. The <name> part of the plugin file doesn't matter, you can use it to have several plugins for the same filetype. Note that it must end in ".vim". Further reading: |filetype-plugins| Documentation for the filetype plugins and information about how to avoid that mappings cause problems. |load-plugins| When the global plugins are loaded during startup. |ftplugin-overrule| Overruling the settings from a global plugin. |write-plugin| How to write a plugin script. |plugin-details| For more information about using plugins or when your plugin doesn't work.
*05.5* Adding a help file *add-local-help* If you are lucky, the plugin you installed also comes with a help file. We will explain how to install the help file, so that you can easily find help for your new plugin. Let us use the "matchit.vim" plugin as an example (it is included with Vim). This plugin makes the "%" command jump to matching HTML tags, if/else/endif in Vim scripts, etc. Very useful, although it's not backwards compatible (that's why it is not enabled by default). This plugin comes with documentation: "matchit.txt". Let's first copy the plugin to the right directory. This time we will do it from inside Vim, so that we can use $VIMRUNTIME. (You may skip some of the "mkdir" commands if you already have the directory.) > :!mkdir ~/.vim :!mkdir ~/.vim/plugin :!cp $VIMRUNTIME/macros/matchit.vim ~/.vim/plugin Now create a "doc" directory in one of the directories in 'runtimepath'. > :!mkdir ~/.vim/doc Copy the help file to the "doc" directory. > :!cp $VIMRUNTIME/macros/matchit.txt ~/.vim/doc Now comes the trick, which allows you to jump to the subjects in the new help file: Generate the local tags file with the |:helptags| command. > :helptags ~/.vim/doc Now you can use the > :help g% command to find help for "g%" in the help file you just added. You can see an entry for the local help file when you do: > :help Go down to the "LOCAL ADDITIONS" section. The title lines from the local help files are automagically added to this section. There you can see which local help files have been added and jump to them through the tag. For writing a local help file, see |write-local-help|.
*05.6* The option window If you are looking for an option that does what you want, you can search in the help files here: |options|. Another way is by using this command: > :options This opens a new window, with a list of options with a one-line explanation. The options are grouped by subject. Move the cursor to a subject and press <Enter> to jump there. Press <Enter> again to jump back. Or use CTRL-O. You can change the value of an option. For example, move to the "displaying text" subject. Then move the cursor down to this line: > set wrap nowrap When you hit <Enter>, the line will change to: > set nowrap wrap The option has now been switched off. Just above this line is a short description of the 'wrap' option. Move the cursor one line up to place it in this line. Now hit <Enter> and you jump to the full help on the 'wrap' option. Use CTRL-O to jump back. For options that take a number or string argument you can edit the value. Then press <Enter> to apply the new value. For example, move the cursor a few lines up to this line: > set so=0 Position the cursor on the zero with "$". Change it into a five with "r5". Then press <Enter> to apply the new value. When you now move the cursor around you will notice that the text starts scrolling before you reach the border. This is what the 'scrolloff' option does, it specifies an offset from the window border where scrolling starts.
*05.7* Often used options There are an awful lot of options. Most of them you will hardly ever use. Some of the more useful ones will be mentioned here. Don't forget you can find more help on these options with the ":help" command, with single quotes before and after the option name. For example: > :help 'wrap' In case you have messed up an option value, you can set it back to the default by putting a ampersand (&) after the option name. Example: > :set iskeyword& NOT WRAPPING LINES Vim normally wraps long lines, so that you can see all of the text. Sometimes it's better to let the text continue right of the window. Then you need to scroll the text left-right to see all of a long line. Switch wrapping of with this command: > :set nowrap Vim will automatically scroll the text when you move to text that is not displayed. To see a context of ten characters, do this: > :set sidescroll=10 This doesn't change the text in the file, only the way it is displayed. WRAPPING MOVEMENT COMMANDS Most commands for moving around will stop moving at the start and end of a line. You can change that with the 'whichwrap' option. This sets it to the default value: > :set whichwrap=b,s This allows the <BS> key, when used in the first position of a line, to move the cursor to the end of the previous line. And the <Space> key moves from the end of a line to the start of the next one. To allow the cursor keys <Left> and <Right> to also wrap, use this command: > :set whichwrap=b,s,<,> This is still only for Normal mode. To let <Left> and <Right> do this in Insert mode as well: > :set whichwrap=b,s,<,>,[,] There are a few other flags that can be added, see 'whichwrap'. VIEWING TABS When there are tabs in a file, you cannot see where they are. To make them visible: > :set list Now every Tab is displayed as ^I. And a $ is displayed at the end of each line, so that you can spot trailing spaces that would otherwise go unnoticed. A disadvantage is that this looks ugly when there are many Tabs in a file. If you have a color terminal, or are using the GUI, Vim can show the spaces and tabs as highlighted characters. Use the 'listchars' option: > :set listchars=tab:>-,trail:- Now every tab will be displayed as ">---" and trailing white space as "-". Looks a lot better, doesn't it? KEYWORDS The 'iskeyword' option specifies which characters can appear in a word: > :set iskeyword < iskeyword=@,48-57,_,192-255 > The "@" stands for all alphabetic letters. "48-57" stands for ASCII characters 48 to 57, which are the numbers 0 to 9. "192-255" are the printable latin characters. Sometimes you will want to include a dash in keywords, so that commands like "w" consider "upper-case" to be one word. You can do it like this: > :set iskeyword+=- :set iskeyword < iskeyword=@,48-57,_,192-255,- If you look at the new value, you will see that Vim has added a comma for you. To remove a character use "-=". For example, to remove the underscore: > :set iskeyword-=_ :set iskeyword < iskeyword=@,48-57,192-255,- This time a comma is automatically deleted. ROOM FOR MESSAGES When Vim starts there is one line at the bottom that is used for messages. When a message is long, it is either truncated, thus you can only see part of it, or the text scrolls and you have to press <Enter> to continue. You can set the 'cmdheight' option to the number of lines used for messages. Example: > :set cmdheight=3 This does mean there is less room to edit text, thus it's a compromise.
*usr_06.txt* For Vim version 6.1. Last change: 2001 Sep 03 Using syntax highlighting Black and white text is boring. With colors your file comes to life. This not only looks nice, it also speeds up your work. Change the colors used for the different sorts of text. Print your text, with the colors you see on the screen. |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
*06.1* Switching it on It all starts with one simple command: > :syntax enable That should work in most situations to get color in your files. Vim will automagically detect the type of file and load the right syntax highlighting. Suddenly comments are blue, keywords brown and strings red. This makes it easy to overview the file. After a while you will find that black&white text slows you down! If you always want to use syntax highlighting, put the "syntax enable" command in your |vimrc| file. If you want syntax highlighting only when the terminal supports colors, you can put this in your |vimrc| file: > if &t_Co > 1 syntax enable endif If you want syntax highlighting only in the GUI version, put the ":syntax enable" command in your |gvimrc| file.
*06.2* No or wrong colors? There can be a number of reasons why you don't see colors: - Your terminal does not support colors. Vim will use bold, italic and underlined text, but this doesn't look very nice. You probably will want to try to get a terminal with colors. For Unix, I recommend the xterm from the XFree86 project: |xfree-xterm|. - Your terminal does support colors, but Vim doesn't know this. Make sure your $TERM setting is correct. For example, when using an xterm that supports colors: > setenv TERM xterm-color < or (depending on your shell): > TERM=xterm-color; export TERM < The terminal name must match the terminal you are using. If it still doesn't work, have a look at |xterm-color|, which shows a few ways to make Vim display colors (not only for an xterm). - The file type is not recognized. Vim doesn't know all file types, and sometimes it's near to impossible to tell what language a file uses. Try this command: > :set filetype < If the result is "filetype=" then the problem is indeed that Vim doesn't know what type of file this is. You can set the type manually: > :set filetype=fortran < To see which types are available, look in the directory $VIMRUNTIME/syntax. For the GUI you can use the Syntax menu. Setting the filetype can also be done with a |modeline|, so that the file will be highlighted each time you edit it. For example, this line can be used in a Makefile (put it near the start or end of the file): > # vim: syntax=make < You might know how to detect the file type yourself. Often the file name extension (after the dot) can be used. See |new-filetype| for how to tell Vim to detect that file type. - There is no highlighting for your file type. You could try using a similar file type by manually setting it as mentioned above. If that isn't good enough, you can write your own syntax file, see |mysyntaxfile|. Or the colors could be wrong: - The colored text is very hard to read. Vim guesses the background color that you are using. If it is black (or another dark color) it will use light colors for text. If it is white (or another light color) it will use dark colors for text. If Vim guessed wrong the text will be hard to read. To solve this, set the 'background' option. For a dark background: > :set background=dark < And for a light background: > :set background=light < Make sure you put this _before_ the ":syntax enable" command, otherwise the colors will already have been set. You could do ":syntax reset" after setting 'background' to make Vim set the default colors again. - The colors are wrong when scrolling bottom to top. Vim doesn't read the whole file to parse the text. It starts parsing wherever you are viewing the file. That saves a lot of time, but sometimes the colors are wrong. A simple fix is hitting CTRL-L. Or scroll back a bit and then forward again. For a real fix, see |:syn-sync|. Some syntax files have a way to make it look further back, see the help for the specific syntax file. For example, |tex.vim| for the TeX syntax.
*06.3* Different colors *:syn-default-override* If you don't like the default colors, you can select another color scheme. In the GUI use the Edit/Color Scheme menu. You can also type the command: > :colorscheme evening "evening" is the name of the color scheme. There are several others you might want to try out. Look in the directory $VIMRUNTIME/colors. When you found the color scheme that you like, add the ":colorscheme" command to your |vimrc| file. You could also write your own color scheme. This is how you do it: 1. Select a color scheme that comes close. Copy this file to your own Vim directory. For Unix, this should work: > !mkdir ~/.vim/colors !cp $VIMRUNTIME/colors/morning.vim ~/.vim/colors/mine.vim < This is done from Vim, because it knows the value of $VIMRUNTIME. 2. Edit the color scheme file. These entries are useful: term attributes in a B&W terminal cterm attributes in a color terminal ctermfg foreground color in a color terminal ctermbg background color in a color terminal gui attributes in the GUI guifg foreground color in the GUI guibg background color in the GUI For example, to make comments green: > :highlight Comment ctermfg=green guifg=green < Attributes you can use for "cterm" and "gui" are "bold" and "underline". If you want both, use "bold,underline". For details see the |:highlight| command. 3. Tell Vim to always use your color scheme. Put this line in your |vimrc|: > colorscheme mine If you want to see what the most often used color combinations look like, use these commands: > :edit $VIMRUNTIME/syntax/colortest.vim :source % You will see text in various color combinations. You can check which ones are readable and look nice.
*06.4* With colors or without colors Displaying text in color takes a lot of effort. If you find the displaying too slow, you might want to disable syntax highlighting for a moment: > :syntax clear When editing another file (or the same one) the colors will come back. *:syn-off* If you want to stop highlighting completely use: > :syntax off This will completely disable syntax highlighting and remove it immediately for all buffers. *:syn-manual* If you want syntax highlighting only for specific files, use this: > :syntax manual This will enable the syntax highlighting, but not switch it on automatically when starting to edit a buffer. To switch highlighting on for the current buffer, set the 'syntax' option: > :set syntax=ON <
*06.5* Printing with colors *syntax-printing* In the MS-Windows version you can print the current file with this command: > :hardcopy You will get the usual printer dialog, where you can select the printer and a few settings. If you have a color printer, the paper output should look the same as what you see inside Vim. But when you use a dark background the colors will be adjusted to look good on white paper. There are several options that change the way Vim prints: 'printdevice' 'printheader' 'printfont' 'printoptions' To print only a range of lines, use Visual mode to select the lines and then type the command: > v100j:hardcopy "v" starts Visual mode. "100j" moves a hundred lines down, they will be highlighted. Then ":hardcopy" will print those lines. You can use other commands to move in Visual mode, of course. This also works on Unix, if you have a PostScript printer. Otherwise, you will have to do a bit more work. You need to convert the text to HTML first, and then print it from a web browser such as Netscape. Convert the current file to HTML with this command: > :source $VIMRUNTIME/syntax/2html.vim You will see it crunching away, this can take quite a while for a large file. Some time later another window shows the HTML code. Now write this somewhere (doesn't matter where, you throw it away later): > :write main.c.html Open this file in your favorite browser and print it from there. If all goes well, the output should look exactly as it does in Vim. See |2html.vim| for details. Don't forget to delete the HTML file when you are done with it. Instead of printing, you could also put the HTML file on a web server, and let others look at the colored text.
*06.6* Further reading |usr_44.txt| Your own syntax highlighted. |syntax| All the details.
*usr_07.txt* For Vim version 6.1. Last change: 2001 Sep 03 Editing more than one file No matter how many files you have, you can edit them without leaving Vim. Define a list of files to work on and jump from one to the other. Copy text from one file and put it in another one. |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
*07.1* Edit another file So far you had to start Vim for every file you wanted to edit. There is a simpler way. To start editing another file, use this command: > :edit foo.txt You can use any file name instead of "foo.txt". Vim will close the current file and open the new one. If the current file has unsaved changes, however, Vim displays an error message and does not open the new file: E37: No write since last change (use ! to override) ~ Note: Vim puts an error ID at the start of each error message. If you do not understand the message or what caused it, look in the help system for this ID. In this case: > :help E37 At this point, you have a number of alternatives. You can write the file using this command: > :write Or you can force Vim to discard your changes and edit the new file, using the force (!) character: > :edit! foo.txt If you want to edit another file, but not write the changes in the current file yet, you can make it hidden: > :hide edit foo.txt The text with changes is still there, but you can't see it. This is further explained in section |22.4|: The buffer list.
*07.2* A list of files You can start Vim to edit a sequence of files. For example: > vim one.c two.c three.c This command starts Vim and tells it that you will be editing three files. Vim displays just the first file. After you have done your thing in this file, to edit the next file you use this command: > :next If you have unsaved changes in the current file, you will get an error message and the ":next" will not work. This is the same problem as with ":edit" mentioned in the previous section. To abandon the changes: > :next! But mostly you want to save the changes and move on to the next file. There is a special command for this: > :wnext This does the same as using two separate commands: > :write :next WHERE AM I? To see which file in the argument list you are editing, look in the window title. It should show something like "(2 of 3)". This means you are editing the second file out of three files. If you want to see the list of files, use this command: > :args This is short for "arguments". The output might look like this: > one.c [two.c] three.c These are the files you started Vim with. The one you are currently editing, "two.c", is in square brackets. MOVING TO OTHER ARGUMENTS To go back one file: > :previous This is just like the ":next" command, except that it moves in the other direction. Again, there is a shortcut command for when you want to write the file first: > :wprevious To move to the very last file in the list: > :last And to move back to the first one again: > :first There is no ":wlast" or "wfirst" command though! You can use a count for ":next" and ":previous". To skip two files forward: > :2next AUTOMATIC WRITING When moving around the files and making changes, you have to remember to use ":write". Otherwise you will get an error message. If you are sure you always want to write modified files, you can tell Vim to automatically write them: > :set autowrite When you are editing a file which you may not want to write, switch it off again: > :set noautowrite EDITING ANOTHER LIST OF FILES You can redefine the list of files without the need to exit Vim and start it again. Use this command to edit three other files: > :args five.c six.c seven.h Or use a wildcard, like it's used in the shell: > :args *.txt Vim will take you to the first file in the list. Again, if the current file has changes, you can either write the file first, or use ":args!" (with ! added) to abandon the changes. DID YOU EDIT THE LAST FILE? *arglist-quit* When you use a list of files, Vim assumes you want to edit them all. To protect you from exiting too early, you will get this error when you didn't edit the last file in the list yet: > E173: 46 more files to edit If you really want to exit, just do it again. Then it will work (but not when you did other commands in between).
*07.3* Jumping from file to file To quickly jump between two files, press CTRL-^ (on English-US keyboards the ^ is above the 6 key). Example: > :args one.c two.c three.c You are now in one.c. > :next Now you are in two.c. Now use CTRL-^ to go back to one.c. Another CTRL-^ and you are back in two.c. Another CTRL-^ and you are in one.c again. If you now do: > :next You are in three.c. Notice that the CTRL-^ command does not change the idea of where you are in the list of files. Only commands like ":next" and ":previous" do that. The file you were previously editing is called the "alternate" file. When you just started Vim CTRL-^ will not work, since there isn't a previous file. PREDEFINED MARKS After jumping to another file, you can use two predefined marks which are very useful: > `" This takes you to the position where the cursor was when you left the file. Another mark that is remembered is the position where you made the last change: > `. Suppose you are editing the file "one.txt". Somewhere halfway the file you use "x" to delete a character. Then you go to the last line with "G" and write the file with ":w". You edit several other files, and then use ":edit one.txt" to come back to "one.txt". If you now use `" Vim jumps to the last line of the file. Using `. takes you to the position where you deleted the character. Even when you move around in the file `" and `. will take you to the remembered position. At least until you make another change or leave the file. FILE MARKS In chapter 4 was explained how you can place a mark in a file with "mx" and jump to that position with "`x". That works within one file. If you edit another file and place marks there, these are specific for that file. Thus each file has its own set of marks, they are local to the file. So far we were using marks with a lowercase letter. There are also marks with an uppercase letter. These are global, they can be used from any file. For example suppose that we are editing the file "foo.txt". Go to halfway the file ("50%") and place the F mark there (F for foo): > 50%mF Now edit the file "bar.txt" and place the B mark (B for bar) at its last line: > GmB Now you can use the "'F" command to jump back to halfway foo.txt. Or edit yet another file, type "'B" and you are at the end of bar.txt again. The file marks are remembered until they are placed somewhere else. Thus you can place the mark, do hours of editing and still be able to jump back to that mark. It's often useful to think of a simple connection between the mark letter and where it is placed. For example, use the H mark in a header file, M in a Makefile and C in a C code file. To see where a specific mark is, give an argument to the ":marks" command: > :marks M You can also give several arguments: > :marks MCP Don't forget that you can use CTRL-O and CTRL-I to jump to older and newer positions without placing marks there.
*07.4* Backup files Usually Vim does not produce a backup file. If you want to have one, all you need to do is execute the following command: > :set backup The name of the backup file is the original file with a ~ added to the end. If your file is named data.txt, for example, the backup file name is data.txt~. If you do not like the fact that the backup files end with ~, you can change the extension: > :set backupext=.bak This will use data.txt.bak instead of data.txt~. Another option that matters here is 'backupdir'. It specifies where the backup file is written. The default, to write the backup in the same directory as the original file, will mostly be the right thing. Note: When the 'backup' option isn't set but the 'writebackup' is, Vim will still create a backup file. However, it is deleted as soon as writing the file was completed successfully. This functions as a safety against losing your original file when writing fails in some way (disk full is the most common cause; being hit by lightning might be another, although less common). KEEPING THE ORIGINAL FILE If you are editing source files, you might want to keep the file before you make any changes. But the backup file will be overwritten each time you write the file. Thus it only contains the previous version, not the first one. To make Vim keep the original file, set the 'patchmode' option. This specifies the extension used for the first backup of a changed file. Usually you would do this: > :set patchmode=.orig When you now edit the file data.txt for the first time, make changes and write the file, Vim will keep a copy of the unchanged file under the name "data.txt.orig". If you make further changes to the file, Vim will notice that "data.txt.orig" already exists and leave it alone. Further backup files will then be called "data.txt~" (or whatever you specified with 'backupext'). If you leave patchmode empty (that is the default), the original file will not be kept.
*07.5* Copy text between files This explains how to copy text from one file to another. Let's start with a simple example. Edit the file that contains the text you want to copy. Move the cursor to the start of the text and press "v". This starts Visual mode. Now move the cursor to the end of the text and press "y". This yanks (copies) the selected text. To copy the above paragraph, you would do: > :edit thisfile /This vjjjj$y Now edit the file you want to put the text in. Move the cursor to the character where you want the text to appear after. Use "p" to put the text there. > :edit otherfile /There p Of course you can use many other commands to yank the text. For example, to select whole lines start Visual mode with "V". Or use CTRL-V to select a rectangular block. Or use "Y" to yank a single line, "yaw" to yank-a-word, etc. The "p" command puts the text after the cursor. Use "P" to put the text before the cursor. Notice that Vim remembers if you yanked a whole line or a block, and puts it back that way. USING REGISTERS When you want to copy several pieces of text from one file to another, having to switch between the files and writing the target file takes a lot of time. To avoid this, copy each piece of text to its own register. A register is a place where Vim stores text. Here we will use the registers named a to z (later you will find out there are others). Let's copy a sentence to the f register (f for First): > "fyas The "yas" command yanks a sentence like before. It's the "f that tells Vim the text should be place in the f register. This must come just before the yank command. Now yank three whole lines to the l register (l for line): > "l3Y The count could be before the "l just as well. To yank a block of text to the b (for block) register: > CTRL-Vjjww"by Notice that the register specification "b is just before the "y" command. This is required. If you would have put it before the "w" command, it would not have worked. Now you have three pieces of text in the f, l and b registers. Edit another file, move around and place the text where you want it: > "fp Again, the register specification "f comes before the "p" command. You can put the registers in any order. And the text stays in the register until you yank something else into it. Thus you can put it as many times as you like. When you delete text, you can also specify a register. Use this to move several pieces of text around. For example, to delete-a-word and write it in the w register: > "wdaw Again, the register specification comes before the delete command "d". APPENDING TO A FILE When collecting lines of text into one file, you can use this command: > :write >> logfile This will write the text of the current file to the end of "logfile". Thus it is appended. This avoids that you have to copy the lines, edit the log file and put them there. Thus you save two steps. But you can only append to the end of a file. To append only a few lines, select them in Visual mode before typing ":write". In chapter 10 you will learn other ways to select a range of lines.
*07.6* Viewing a file Sometimes you only want to see what a file contains, without the intention to ever write it back. There is the risk that you type ":w" without thinking and overwrite the original file anyway. To avoid this, edit the file read-only. To start Vim in readonly mode, use this command: > vim -R file On Unix this command should do the same thing: > view file You are now editing "file" in read-only mode. When you try using ":w" you will get an error message and the file won't be written. When you try to make a change to the file Vim will give you a warning: W10: Warning: Changing a readonly file ~ The change will be done though. This allows for formatting the file, for example, to be able to read it easily. If you make changes to a file and forgot that it was read-only, you can still write it. Add the ! to the write command to force writing. If you really want to forbid making changes in a file, do this: > vim -M file Now every attempt to change the text will fail. The help files are like this, for example. If you try to make a change you get this error message: E21: Cannot make changes, 'modifiable' is off ~ You could use the -M argument to setup Vim to work in a viewer mode. This is only voluntary though, since these commands will remove the protection: > :set modifiable :set write
*07.7* Changing the file name A clever way to start editing a new file is by using an existing file that contains most of what you need. For example, you start writing a new program to move a file. You know that you already have a program that copies a file, thus you start with: > :edit copy.c You can delete the stuff you don't need. Now you need to save the file under a new name. The ":saveas" command can be used for this: > :saveas move.c Vim will write the file under the given name, and edit that file. Thus the next time you do ":write", it will write "move.c". "copy.c" remains unmodified. When you want to change the name of the file you are editing, but don't want to write the file, you can use this command: > :file move.c Vim will mark the file as "not edited". This means that Vim knows this is not the file you started editing. When you try to write the file, you might get this message: E13: File exists (use ! to override) ~ This protects you from accidentally overwriting another file.
*usr_08.txt* For Vim version 6.1. Last change: 2002 Mar 09 Splitting windows Display two different files above each other. Or view two locations in the file at the same time. See the difference between two files by putting them side by side. All this is possible with split 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
*08.1* Split a window The easiest way to open a new window is to use the following command: > :split This command splits the screen into two windows and leaves the cursor in the top one: +----------------------------------+ |/* file one.c */ | |~ | |~ | |one.c=============================| |/* file one.c */ | |~ | |one.c=============================| | | +----------------------------------+ What you see here is two windows on the same file. The line with "====" is that status line. It displays information about the window above it. (in practice the status line will be in reverse video.) The two windows allow you to view two parts of the same file. For example, you could make the top window show the variable declarations of a program, and the bottom one the code that uses these variables. The CTRL-W w command can be used to jump between the windows. If you are in the top window, CTRL-W w jumps to the window below it. If you are in the bottom window it will jump to the first window. (CTRL-W CTRL-W does the same thing, in case you let go of the CTRL key a bit later). CLOSE THE WINDOW To close a window, use the command: > :close Actually, any command that quits editing a file works, like ":quit" and "ZZ". But ":close" prevents you from accidentally exiting Vim when you close the last window. CLOSING ALL OTHER WINDOWS If you have opened a whole bunch of windows, but now want to concentrate on one of them, this command will be useful: > :only This closes all windows, except for the current one. If any of the other windows has changes, you will get an error message and that window won't be closed.
*08.2* Split a window on another file The following command opens a second window and starts editing the given file: > :split two.c If you were editing one.c, then the result looks like this: +----------------------------------+ |/* file two.c */ | |~ | |~ | |two.c=============================| |/* file one.c */ | |~ | |one.c=============================| | | +----------------------------------+ To open a window on a new, empty file, use this: > :new You can repeat the ":split" and ":new" commands to create as many windows as you like.
*08.3* Window size The :split command can take a number argument. If specified, this will be the height of the new window. For example, the following opens a new window three lines high and starts editing the file alpha.c: > :3split alpha.c For existing windows you can change the size in several ways. When you have a working mouse, it is easy: Move the mouse pointer to the status line that separates two windows, and drag it up or down. To increase the size of a window: > CTRL-W + To decrease it: > CTRL-W - Both of these commands take a count and increase or decrease the window size by that many lines. Thus "4 CTRL-W +" make the window four lines higher. To set the window height to a specified number of lines: > {height}CTRL-W _ That's: a number {height}, CTRL-W and then an underscore (the - key with Shift on English-US keyboards). To make a window as high as it can be, use the CTRL-W _ command without a count. USING THE MOUSE In Vim you can do many things very quickly from the keyboard. Unfortunately, the window resizing commands require quite a bit of typing. In this case, using the mouse is faster. Position the mouse pointer on a status line. Now press the left mouse button and drag. The status line will move, thus making the window on one side higher and the other smaller. OPTIONS The 'winheight' option can be set to a minimal desired height of a window and 'winminheight' to a hard minimum height. Likewise, there is 'winwidth' for the minimal desired width and 'winminwidth' for the hard minimum width. The 'equalalways' option, when set, makes Vim equalize the windows sizes when a window is closed or opened.
*08.4* Vertical splits The ":split" command creates the new window above the current one. To make the window appear at the left side, use: > :vsplit or: > :vsplit two.c The result looks something like this: +--------------------------------------+ |/* file two.c */ |/* file one.c */ | |~ |~ | |~ |~ | |~ |~ | |two.c===============one.c=============| | | +--------------------------------------+ Actually, the | lines in the middle will be in reverse video. This is called the vertical separator. It separates the two windows left and right of it. There is also the "vnew" command, to open a vertically split window on a new, empty file. Another way to do this: > :vertical new The ":vertical" command can be inserted before another command that splits a window. This will cause that command to split the window vertically instead of horizontally. (if the command doesn't split a window, it works unmodified). MOVING BETWEEN WINDOWS Since you can split windows horizontally and vertically as much as you like, you can create any layout of windows. Then you can use these commands to move between them: CTRL-W h move to the window on the left CTRL-W j move to the window below CTRL-W k move to the window above CTRL-W l move to the window on the right CTRL-W t move to the TOP window CTRL-W b move to the BOTTOM window You will notice the same letters as used for moving the cursor. And the cursor keys can also be used, if you like. More commands to move to other windows: |Q_wi|
*08.5* Moving windows You have split a few windows, but now they are in the wrong place. Then you need a command to move the window somewhere else. For example, you have three windows like this: +----------------------------------+ |/* file two.c */ | |~ | |~ | |two.c=============================| |/* file three.c */ | |~ | |~ | |three.c===========================| |/* file one.c */ | |~ | |one.c=============================| | | +----------------------------------+ Clearly the last one should be at the top. Go to that window (using CTRL-W w) and the type this command: > CTRL-W K This uses the uppercase letter K. What happens is that the window is moved to the very top. You will notice that K is again used for moving upwards. When you have vertical splits, CTRL-W K will move the current window to the top and make it occupy the full with of the Vim window. If this is your layout: +-------------------------------------------+ |/* two.c */ |/* three.c */ |/* one.c */ | |~ |~ |~ | |~ |~ |~ | |~ |~ |~ | |~ |~ |~ | |~ |~ |~ | |two.c=========three.c=========one.c========| | | +-------------------------------------------+ Then using CTRL-W K in the middle window (three.c) will result in: +-------------------------------------------+ |/* three.c */ | |~ | |~ | |three.c====================================| |/* two.c */ |/* one.c */ | |~ |~ | |two.c==================one.c===============| | | +-------------------------------------------+ The other three similar commands (you can probably guess these now): CTRL-W H move window to the far left CTRL-W J move window to the bottom CTRL-W L move window to the far right
*08.6* Commands for all windows When you have several windows open and you want to quit Vim, you can close each window separately. A quicker way is using this command: > :qall This stands for "quit all". If any of the windows contain changes, Vim will not exit. The cursor will automatically be positioned in a window with changes. You can then either use ":write" to save the changes, or ":quit!" to throw them away. If you know there are windows with changes, and you want to save all these changes, use this command: > :wall This stands for ":write all". But actually, it only writes files with changes. Vim knows it doesn't make sense to write files that were not changed. And then there is the combination of ":qall" and "wall": the "write and quit all" command: > :wqall This writes all modified files and quits Vim. Finally, there is a command that quits Vim and throws away all changes: > :qall! Be careful, there is no way to undo this command! OPENING A WINDOW FOR ALL ARGUMENTS To make Vim open a window for each file, start it with the "-o" argument: > vim -o one.txt two.txt three.txt This results in: +-------------------------------+ |file one.txt | |~ | |one.txt========================| |file two.txt | |~ | |two.txt========================| |file three.txt | |~ | |three.txt======================| | | +-------------------------------+ The "-O" argument is used to get vertically split windows. When vim is already running, the ":all" command opens a window for each file in the argument list. ":vertical all" does it with vertical splits.
*08.7* Viewing differences with vimdiff There is a special way to start Vim, which shows the differences between two files. Let's take a file "main.c" and insert a few characters in one line. Write this file with the 'backup' option set, so that the backup file "main.c~" will contain the previous version of the file. Type this command in a shell (not in Vim): > vimdiff main.c~ main.c Vim will start, with two windows side by side. You will only see the line in which you added characters, and a few lines above and below it. VV VV +-----------------------------------------+ |+ +--123 lines: /* a|+ +--123 lines: /* a| <- fold | text | text | | text | text | | text | text | | text | changed text | <- changed line | text | text | | text | ------------------| <- deleted line | text | text | | text | text | | text | text | |+ +--432 lines: text|+ +--432 lines: text| <- fold | ~ | ~ | | ~ | ~ | |main.c~==============main.c==============| | | +-----------------------------------------+ (This picture doesn't show the highlighting, use the vimdiff command for a better look.) The lines that were not modified have been collapsed into one line. This is called a closed fold. The are indicated in the picture with "<- fold". Thus the single fold line at the top stands for 123 text lines. These lines are equal in both files. The line marked with "<- changed line" is highlighted, and the inserted text is displayed with another color. This clearly shows what the difference is between the two files. The line that was deleted is displayed with "---" in the main.c window. See the "<- deleted line" marker in the picture. These characters are not really there. They just fill up main.c, so that it displays the same number of lines as the other window. THE FOLD COLUMN Each window has a column on the left with a slightly different background. In the picture above these are indicated with "VV". You notice there is a plus character there, in front of each closed fold. Move the mouse pointer to that plus and click the left button. The fold will open, and you can see the text that it contains. The fold column contains a minus sign for an open fold. If you click on this -, the fold will close. Obviously, this only works when you have a working mouse. You can also use "zo" to open a fold and "zc" to close it. DIFFING IN VIM Another way to start in diff mode can be done from inside Vim. Edit the "main.c" file, then make a split and show the differences: > :edit main.c :vertical diffsplit main.c~ The ":vertical" command is used to make the window split vertically. If you omit this, you will get a horizontal split. If you have a patch or diff file, you can use the third way to start diff mode. First edit the file to which the patch applies. Then tell Vim the name of the patch file: > :edit main.c :vertical diffpatch main.c.diff WARNING: The patch file must contain only one patch, for the file you are editing. Otherwise you will get a lot of error messages, and some files might be patched unexpectedly. The patching will only be done to the copy of the file in Vim. The file on your harddisk will remain unmodified (until you decide to write the file). SCROLL BINDING When the files have more changes, you can scroll in the usual way. Vim will try to keep both the windows start at the same position, so you can easily see the differences side by side. When you don't want this for a moment, use this command: > :set noscrollbind JUMPING TO CHANGES When you have disabled folding in some way, it may be difficult to find the changes. Use this command to jump forward to the next change: > ]c To go the other way use: > [c Prepended a count to jump further away. REMOVING CHANGES You can move text from one window to the other. This either removes differences or adds new ones. Vim doesn't keep the highlighting updated in all situations. To update it use this command: > :diffupdate To remove a difference, you can move the text in a highlighted block from one window to another. Take the "main.c" and "main.c~" example above. Move the cursor to the left window, on the line that was deleted in the other window. Now type this command: > dp The change will be removed by putting the text of the current window in the other window. "dp" stands for "diff put". You can also do it the other way around. Move the cursor to the right window, to the line where "changed" was inserted. Now type this command: > do The change will now be removed by getting the text from the other window. Since there are no changes left now, Vim puts all text in a closed fold. "do" stands for "diff obtain". "dg" would have been better, but that already has a different meaning ("dgg" deletes from the cursor until the first line). For details about diff mode, see |vimdiff|.
*08.8* Various The 'laststatus' option can be used to specify when the last window has a statusline: 0 never 1 only when there are split windows (the default) 2 always Many commands that edit another file have a variant that splits the window. For Command-line commands this is done by prepending an "s". For example: ":tag" jumps to a tag, ":stag" splits the window and jumps to a tag. For Normal mode commands a CTRL-W is prepended. CTRL-^ jumps to the alternate file, CTRL-W CTRL-^ splits the window and edits the alternate file. The 'splitbelow' option can be set to make a new window appear below the current window. The 'splitright' option can be set to make a vertically split window appear right of the current window. When splitting a window you can prepend a modifier command to tell where the window is to appear: :leftabove {cmd} left or above the current window :aboveleft {cmd} idem :rightbelow {cmd} right or below the current window :belowright {cmd} idem :topleft {cmd} at the top or left of the Vim window :botright {cmd} at the bottom or right of the Vim window
*usr_09.txt* For Vim version 6.1. Last change: 2001 Sep 03 Using the GUI Vim works in an ordinary terminal. GVim can do the same things and a few more. The GUI offers menus, a toolbar, scrollbars and other items. This chapter is about these extra things that the GUI offers. |09.1| Parts of the GUI |09.2| Using the mouse |09.3| The clipboard |09.4| Select mode
*09.1* Parts of the GUI You might have an icon on your desktop that starts gVim. Otherwise, one of these commands should do it: > gvim file.txt vim -g file.txt If this doesn't work you don't have a version of Vim with GUI support. You will have to install one first. Vim will open a window and display "file.txt" in it. What the window looks like depends on the version of Vim. It should resemble the following picture (for as far as this can be shown in ASCII!). +----------------------------------------------------+ | file.txt + (~/dir) - VIM X | <- window title +----------------------------------------------------+ | File Edit Tools Syntax Buffers Window Help | <- menubar +----------------------------------------------------+ | aaa bbb ccc ddd eee fff ggg hhh iii jjj | <- toolbar | aaa bbb ccc ddd eee fff ggg hhh iii jjj | +----------------------------------------------------+ | file text | ^ | | ~ | # | | ~ | # | <- scrollbar | ~ | # | | ~ | # | | ~ | # | | | V | +----------------------------------------------------+ The largest space is occupied by the file text. This shows the file in the same way as in a terminal. With some different colors and another font perhaps. THE WINDOW TITLE At the very top is the window title. This is drawn by your window system. Vim will set the title to show the name of the current file. First comes the name of the file. Then some special characters and the directory of the file in parens. These special character can be present: - The file cannot be modified (e.g., a help file) + The file contains changes = The file is read-only =+ The file is read-only, contains changes anyway If nothing is shown you have an ordinary, unchanged file. THE MENUBAR You know how menus work, right? Vim has the usual items, plus a few more. Browse them to get an idea of what you can use them for. A relevant submenu is Edit/Global Settings. You will find these entries: Toggle Toolbar make the toolbar appear/disappear Toggle Bottom Scrollbar make a scrollbar appear/disappear at the bottom Toggle Left Scrollbar make a scrollbar appear/disappear at the left Toggle Right Scrollbar make a scrollbar appear/disappear at the right On most systems you can tear-off the menus. Select the top item of the menu, the one that looks like a dashed line. You will get a separate window with the items of the menu. It will hang around until you close the window. THE TOOLBAR This contains icons for the most often used actions. Hopefully the icons are self-explanatory. There are tooltips to get an extra hint (move the mouse pointer to the icon without clicking and don't move it for a second). The "Edit/Global Settings/Toggle Toolbar" menu item can be used to make the toolbar disappear. If you never want a toolbar, use this command in your vimrc file: > :set guioptions-=T This removes the 'T' flag from the 'guioptions' option. Other parts of the GUI can also be enabled or disabled with this option. See the help for it. THE SCROLLBARS By default there is one scrollbar on the right. It does the obvious thing. When you split the window, each window will get its own scrollbar. You can make a horizontal scrollbar appear with the menu item Edit/Global Settings/Toggle Bottom Scrollbar. This is useful in diff mode, or when the 'wrap' option has been reset (more about that later). When there are vertically split windows, only the windows on the right side will have a scrollbar. However, when you move the cursor to a window on the left, it will be this one the that scrollbar controls. This takes a bit of time to get used to. When you work with vertically split windows, consider adding a scrollbar on the left. This can be done with a menu item, or with the 'guioptions' option: > :set guioptions+=l This adds the 'l' flag to 'guioptions'.