usr_02.txt (24452B)
1 *usr_02.txt* For Vim version 9.2. Last change: 2026 Aug 25 2 3 4 VIM USER MANUAL by Bram Moolenaar 5 6 7 The first steps in Vim 8 9 10 This chapter provides just enough information to edit a file with Vim. Not 11 well or fast, but you can edit. Take some time to practice with these 12 commands, they form the base for what follows. 13 14 |02.1| Running Vim for the First Time 15 |02.2| Inserting text 16 |02.3| Moving around 17 |02.4| Deleting characters 18 |02.5| Undo and Redo 19 |02.6| Other editing commands 20 |02.7| Getting out 21 |02.8| Finding help 22 23 Next chapter: |usr_03.txt| Moving around 24 Previous chapter: |usr_01.txt| About the manuals 25 Table of contents: |usr_toc.txt| 26 27 ============================================================================== 28 *02.1* Running Vim for the First Time 29 30 To start Vim, enter this command: > 31 32 gvim file.txt 33 34 In UNIX you can type this at any command prompt. If you are running Microsoft 35 Windows, open a Command Prompt and enter the command. 36 In either case, Vim starts editing a file called file.txt. Because this 37 is a new file, you get a blank window. This is what your screen will look 38 like: 39 40 +---------------------------------------+ 41 |# | 42 |~ | 43 |~ | 44 |~ | 45 |~ | 46 |"file.txt" [New file] | 47 +---------------------------------------+ 48 ('#' is the cursor position.) 49 50 The tilde (~) lines indicate lines not in the file. In other words, when Vim 51 runs out of file to display, it displays tilde lines. At the bottom of the 52 screen, a message line indicates the file is named file.txt and shows that you 53 are creating a new file. The message information is temporary and other 54 information overwrites it. 55 56 57 THE VIM COMMAND 58 59 The gvim command causes the editor to create a new window for editing. If you 60 use this command: > 61 62 vim file.txt 63 64 the editing occurs inside your command window. In other words, if you are 65 running inside an xterm, the editor uses your xterm window. If you are using 66 an MS-Windows command prompt window, the editing occurs inside this window. 67 The text in the window will look the same for both versions, but with gvim you 68 have extra features, like a menu bar. More about that later. 69 70 ============================================================================== 71 *02.2* Inserting text 72 73 The Vim editor is a modal editor. That means that the editor behaves 74 differently, depending on which mode you are in. The two basic modes are 75 called Normal mode and Insert mode. In Normal mode the characters you type 76 are commands. In Insert mode the characters are inserted as text. 77 Since you have just started Vim it will be in Normal mode. To start Insert 78 mode you type the "i" command (i for Insert). Then you can enter 79 the text. It will be inserted into the file. Do not worry if you make 80 mistakes; you can correct them later. To enter the following programmer's 81 limerick, this is what you type: > 82 83 iA very intelligent turtle 84 Found programming UNIX a hurdle 85 86 After typing "turtle" you press the <Enter> key to start a new line. Finally 87 you press the <Esc> key to stop Insert mode and go back to Normal mode. You 88 now have two lines of text in your Vim window: 89 90 +---------------------------------------+ 91 |A very intelligent turtle | 92 |Found programming UNIX a hurdle | 93 |~ | 94 |~ | 95 | | 96 +---------------------------------------+ 97 98 99 WHAT IS THE MODE? 100 101 To be able to see what mode you are in, type this command: > 102 103 :set showmode 104 105 You will notice that when typing the colon Vim moves the cursor to the last 106 line of the window. That's where you type colon commands (commands that start 107 with a colon). Finish this command by pressing the <Enter> key (all commands 108 that start with a colon are finished this way). 109 Now, if you type the "i" command Vim will display --INSERT-- at the bottom 110 of the window. This indicates you are in Insert mode. 111 112 +---------------------------------------+ 113 |A very intelligent turtle | 114 |Found programming UNIX a hurdle | 115 |~ | 116 |~ | 117 |-- INSERT -- | 118 +---------------------------------------+ 119 120 If you press <Esc> to go back to Normal mode the last line will be made blank. 121 122 123 GETTING OUT OF TROUBLE 124 125 One of the problems for Vim novices is mode confusion, which is caused by 126 forgetting which mode you are in or by accidentally typing a command that 127 switches modes. To get back to Normal mode, no matter what mode you are in, 128 press the <Esc> key. Sometimes you have to press it twice. If Vim beeps back 129 at you, you already are in Normal mode. 130 131 ============================================================================== 132 *02.3* Moving around 133 134 After you return to Normal mode, you can move around by using these keys: 135 136 h left *hjkl* 137 j down 138 k up 139 l right 140 141 At first, it may appear that these commands were chosen at random. After all, 142 who ever heard of using l for right? But actually, there is a very good 143 reason for these choices: Moving the cursor is the most common thing you do in 144 an editor, and these keys are on the home row of your right hand. In other 145 words, these commands are placed where you can type them the fastest 146 (especially when you type with ten fingers). 147 148 Note: 149 You can also move the cursor by using the arrow keys. If you do, 150 however, you greatly slow down your editing because to press the arrow 151 keys, you must move your hand from the text keys to the arrow keys. 152 Considering that you might be doing it hundreds of times an hour, this 153 can take a significant amount of time. 154 Also, there are keyboards which do not have arrow keys, or which 155 locate them in unusual places; therefore, knowing the use of the hjkl 156 keys helps in those situations. 157 158 One way to remember these commands is that h is on the left, l is on the 159 right and j points down. In a picture: > 160 161 k 162 h l 163 j 164 165 The best way to learn these commands is by using them. Use the "i" command to 166 insert some more lines of text. Then use the hjkl keys to move around and 167 insert a word somewhere. Don't forget to press <Esc> to go back to Normal 168 mode. The |vimtutor| is also a nice way to learn by doing. 169 170 For Japanese users, Hiroshi Iwatani suggested using this: 171 172 Komsomolsk 173 ^ 174 | 175 Huan Ho <--- ---> Los Angeles 176 (Yellow river) | 177 v 178 Java (the island, not the programming language) 179 180 ============================================================================== 181 *02.4* Deleting characters 182 183 To delete a character, move the cursor over it and type "x". (This is a 184 throwback to the old days of the typewriter, when you deleted things by typing 185 xxxx over them.) Move the cursor to the beginning of the first line, for 186 example, and type xxxxxxx (seven x's) to delete "A very ". The result should 187 look like this: 188 189 +---------------------------------------+ 190 |intelligent turtle | 191 |Found programming UNIX a hurdle | 192 |~ | 193 |~ | 194 | | 195 +---------------------------------------+ 196 197 Now you can insert new text, for example by typing: > 198 199 iA young <Esc> 200 201 This begins an insert (the i), inserts the words "A young", and then exits 202 insert mode (the final <Esc>). The result: 203 204 +---------------------------------------+ 205 |A young intelligent turtle | 206 |Found programming UNIX a hurdle | 207 |~ | 208 |~ | 209 | | 210 +---------------------------------------+ 211 212 213 DELETING A LINE 214 215 To delete a whole line use the "dd" command. The following line will 216 then move up to fill the gap: 217 218 +---------------------------------------+ 219 |Found programming UNIX a hurdle | 220 |~ | 221 |~ | 222 |~ | 223 | | 224 +---------------------------------------+ 225 226 227 DELETING A LINE BREAK 228 229 In Vim you can join two lines together, which means that the line break 230 between them is deleted. The "J" command does this. 231 Take these two lines: 232 233 A young intelligent ~ 234 turtle ~ 235 236 Move the cursor to the first line and press "J": 237 238 A young intelligent turtle ~ 239 240 ============================================================================== 241 *02.5* Undo and Redo 242 243 Suppose you delete too much. Well, you can type it in again, but an easier 244 way exists. The "u" command undoes the last edit. Take a look at this in 245 action: After using "dd" to delete the first line, "u" brings it back. 246 Another one: Move the cursor to the A in the first line: 247 248 A young intelligent turtle ~ 249 250 Now type xxxxxxx to delete "A young". The result is as follows: 251 252 intelligent turtle ~ 253 254 Type "u" to undo the last delete. That delete removed the g, so the undo 255 restores the character. 256 257 g intelligent turtle ~ 258 259 The next "u" command restores the next-to-last character deleted: 260 261 ng intelligent turtle ~ 262 263 The next "u" command gives you the u, and so on: 264 265 ung intelligent turtle ~ 266 oung intelligent turtle ~ 267 young intelligent turtle ~ 268 young intelligent turtle ~ 269 A young intelligent turtle ~ 270 271 Note: 272 If you type "u" twice, and the result is that you get the same text 273 back, you have Vim configured to work Vi compatible. Look here to fix 274 this: |not-compatible|. 275 This text assumes you work "The Vim Way". You might prefer to use 276 the good old Vi way, but you will have to watch out for small 277 differences in the text then. 278 279 280 REDO 281 282 If you undo too many times, you can press CTRL-R (redo) to reverse the 283 preceding command. In other words, it undoes the undo. To see this in 284 action, press CTRL-R twice. The character A and the space after it disappear: 285 286 young intelligent turtle ~ 287 288 There's a special version of the undo command, the "U" (undo line) command. 289 The undo line command undoes all the changes made on the last line that was 290 edited. Typing this command twice cancels the preceding "U". 291 292 A very intelligent turtle ~ 293 xxxx Delete very 294 295 A intelligent turtle ~ 296 xxxxxx Delete turtle 297 298 A intelligent ~ 299 Restore line with "U" 300 A very intelligent turtle ~ 301 Undo "U" with "u" 302 A intelligent ~ 303 304 The "U" command is a change by itself, which the "u" command undoes and CTRL-R 305 redoes. This might be a bit confusing. Don't worry, with "u" and CTRL-R you 306 can go to any of the situations you had. More about that in section |32.2|. 307 308 ============================================================================== 309 *02.6* Other editing commands 310 311 Vim has a large number of commands to change the text. See |Q_in| and below. 312 Here are a few often used ones. 313 314 315 APPENDING 316 317 The "i" command inserts a character before the character under the cursor. 318 That works fine; but what happens if you want to add stuff to the end of the 319 line? For that you need to insert text after the cursor. This is done with 320 the "a" (append) command. 321 For example, to change the line 322 323 and that's not saying much for the turtle. ~ 324 to 325 and that's not saying much for the turtle!!! ~ 326 327 move the cursor over to the dot at the end of the line. Then type "x" to 328 delete the period. The cursor is now positioned at the end of the line on the 329 e in turtle. Now type > 330 331 a!!!<Esc> 332 333 to append three exclamation points after the e in turtle: 334 335 and that's not saying much for the turtle!!! ~ 336 337 338 OPENING UP A NEW LINE 339 340 The "o" command creates a new, empty line below the cursor and puts Vim in 341 Insert mode. Then you can type the text for the new line. 342 Suppose the cursor is somewhere in the first of these two lines: 343 344 A very intelligent turtle ~ 345 Found programming UNIX a hurdle ~ 346 347 If you now use the "o" command and type new text: > 348 349 oThat liked using Vim<Esc> 350 351 The result is: 352 353 A very intelligent turtle ~ 354 That liked using Vim ~ 355 Found programming UNIX a hurdle ~ 356 357 The "O" command (uppercase) opens a line above the cursor. 358 359 360 USING A COUNT 361 362 Suppose you want to move up nine lines. You can type "kkkkkkkkk" or you can 363 enter the command "9k". In fact, you can precede many commands with a number. 364 Earlier in this chapter, for instance, you added three exclamation points to 365 the end of a line by typing "a!!!<Esc>". Another way to do this is to use the 366 command "3a!<Esc>". The count of 3 tells the command that follows to triple 367 its effect. Similarly, to delete three characters, use the command "3x". The 368 count always comes before the command it applies to. 369 370 ============================================================================== 371 *02.7* Getting out 372 373 To exit, use the "ZZ" command. This command writes the file and exits. 374 375 Note: 376 Unlike many other editors, Vim does not automatically make a backup 377 file. If you type "ZZ", your changes are committed and there's no 378 turning back. You can configure the Vim editor to produce backup 379 files; see |07.4|. 380 381 382 DISCARDING CHANGES 383 384 Sometimes you will make a sequence of changes and suddenly realize you were 385 better off before you started. Not to worry; Vim has a 386 quit-and-throw-things-away command. It is: > 387 388 :q! 389 390 Don't forget to press <Enter> to finish the command. 391 392 For those of you interested in the details, the three parts of this command 393 are the colon (:), which enters Command-line mode; the q command, which tells 394 the editor to quit; and the override command modifier (!). 395 The override command modifier is needed because Vim is reluctant to throw 396 away changes. If you were to just type ":q", Vim would display an error 397 message and refuse to exit: 398 399 E37: No write since last change (use ! to override) ~ 400 401 By specifying the override, you are in effect telling Vim, "I know that what 402 I'm doing looks stupid, but I really want to do this." 403 404 If you want to continue editing with Vim: The ":e!" command reloads the 405 original version of the file. 406 407 ============================================================================== 408 *02.8* Finding help 409 410 Everything you always wanted to know can be found in the Vim help files. 411 Don't be afraid to ask! 412 413 If you know what you are looking for, it is usually easier to search for it 414 using the help system, instead of using Google. Because the subjects follow 415 a certain style guide. 416 417 Also the help has the advantage of belonging to your particular Vim version. 418 You won't see help for commands added later. These would not work for you. 419 420 To get generic help use this command: > 421 422 :help 423 424 You could also use the first function key <F1>. If your keyboard has a <Help> 425 key it might work as well. 426 If you don't supply a subject, ":help" displays the general help window. 427 The creators of Vim did something very clever (or very lazy) with the help 428 system: They made the help window a normal editing window. You can use all 429 the normal Vim commands to move through the help information. Therefore h, j, 430 k, and l move left, down, up and right. 431 To get out of the help window, use the same command you use to get out of 432 the editor: "ZZ". This will only close the help window, not exit Vim. 433 434 As you read the help text, you will notice some text enclosed in vertical bars 435 (for example, |help|). This indicates a hyperlink. If you position the 436 cursor anywhere between the bars and press CTRL-] (jump to tag), the help 437 system takes you to the indicated subject. (For reasons not discussed here, 438 the Vim terminology for a hyperlink is tag. So CTRL-] jumps to the location 439 of the tag given by the word under the cursor.) 440 After a few jumps, you might want to go back. CTRL-T (pop tag) takes you 441 back to the preceding position. CTRL-O (jump to older position) also works 442 nicely here. 443 At the top of the help screen, there is the notation "*help.txt*". This 444 name between "*" characters is used by the help system to define a tag 445 (hyperlink destination). 446 See |29.1| for details about using tags. 447 448 To get help on a given subject, use the following command: > 449 450 :help {subject} 451 452 To get help on the "x" command, for example, enter the following: > 453 454 :help x 455 456 To find out how to delete text, use this command: > 457 458 :help deleting 459 460 To get a complete index of all Vim commands, use the following command: > 461 462 :help index 463 464 When you need to get help for a control character command (for example, 465 CTRL-A), you need to spell it with the prefix "CTRL-". > 466 467 :help CTRL-A 468 469 The Vim editor has many different modes. By default, the help system displays 470 the normal-mode commands. For example, the following command displays help 471 for the normal-mode CTRL-H command: > 472 473 :help CTRL-H 474 475 To identify other modes, use a mode prefix. If you want the help for the 476 insert-mode version of a command, use "i_". For CTRL-H this gives you the 477 following command: > 478 479 :help i_CTRL-H 480 481 When you start the Vim editor, you can use several command-line arguments. 482 These all begin with a dash (-). To find what the -t argument does, for 483 example, use the command: > 484 485 :help -t 486 487 The Vim editor has a number of options that enable you to configure and 488 customize the editor. If you want help for an option, you need to enclose it 489 in single quotation marks. To find out what the 'number' option does, for 490 example, use the following command: > 491 492 :help 'number' 493 494 The table with all mode prefixes can be found below: |help-summary|. 495 496 Special keys are enclosed in angle brackets. To find help on the up-arrow key 497 in Insert mode, for instance, use this command: > 498 499 :help i_<Up> 500 501 If you see an error message that you don't understand, for example: 502 503 E37: No write since last change (use ! to override) ~ 504 505 You can use the error ID at the start to find help about it: > 506 507 :help E37 508 509 510 Summary: *help-summary* > 511 512 1) Use Ctrl-D after typing a topic and let Vim show all available topics. 513 Or press Tab to complete: > 514 :help some<Tab> 515 < More information on how to use the help: > 516 :help helphelp 517 518 2) Follow the links in bars to related help. You can go from the detailed 519 help to the user documentation, which describes certain commands more from 520 a user perspective and less detailed. E.g. after: > 521 :help pattern.txt 522 < You can see the user guide topics |03.9| and |usr_27.txt| in the 523 introduction. 524 525 3) Options are enclosed in single apostrophes. To go to the help topic for 526 the list option: > 527 :help 'list' 528 < If you only know you are looking for a certain option, you can also do: > 529 :help options.txt 530 < to open the help page which describes all option handling and then search 531 using regular expressions, e.g. textwidth. 532 Certain options have their own namespace, e.g.: > 533 :help cpo-<letter> 534 < for the corresponding flag of the 'cpoptions' settings, substitute <letter> 535 by a specific flag, e.g.: > 536 :help cpo-; 537 < And for the 'guioptions' flags: > 538 :help go-<letter> 539 540 4) Normal mode commands do not have a prefix. To go to the help page for the 541 "gt" command: > 542 :help gt 543 544 5) Insert mode commands start with i_. Help for deleting a word: > 545 :help i_CTRL-W 546 547 6) Visual mode commands start with v_. Help for jumping to the other side of 548 the Visual area: > 549 :help v_o 550 551 7) Command line editing and arguments start with c_. Help for using the 552 command argument %: > 553 :help c_% 554 555 8) Ex-commands always start with ":", so to go to the ":s" command help: > 556 :help :s 557 558 9) Commands specifically for debugging start with ">". To go to the help 559 for the "cont" debug command: > 560 :help >cont 561 562 10) Key combinations. They usually start with a single letter indicating 563 the mode for which they can be used. E.g.: > 564 :help i_CTRL-X 565 < takes you to the family of CTRL-X commands for insert mode which can be 566 used to auto-complete different things. Note, that certain keys will 567 always be written the same, e.g. Control will always be CTRL. 568 For normal mode commands there is no prefix and the topic is available at 569 :h CTRL-<Letter>. E.g. > 570 :help CTRL-W 571 < In contrast > 572 :help c_CTRL-R 573 < will describe what the CTRL-R does when entering commands in the Command 574 line and > 575 :help v_CTRL-A 576 < talks about incrementing numbers in visual mode and > 577 :help g_CTRL-A 578 < talks about the "g<C-A>" command (e.g. you have to press "g" then 579 <CTRL-A>). Here the "g" stands for the normal command "g" which always 580 expects a second key before doing something similar to the commands 581 starting with "z". 582 583 11) Regexp items always start with /. So to get help for the "\+" quantifier 584 in Vim regexps: > 585 :help /\+ 586 < If you need to know everything about regular expressions, start reading 587 at: > 588 :help pattern.txt 589 590 12) Registers always start with "quote". To find out about the special ":" 591 register: > 592 :help quote: 593 594 13) Vim script is available at > 595 :help eval.txt 596 < Certain aspects of the language are available at :h expr-X where "X" is a 597 single letter. E.g. > 598 :help expr-! 599 < will take you to the topic describing the "!" (Not) operator for Vim 600 script. 601 Also important is > 602 :help function-list 603 < to find a short description of all functions available. Help topics for 604 Vim script functions always include the "()", so: > 605 :help append() 606 < talks about the append Vim script function rather than how to append text 607 in the current buffer. 608 609 14) Mappings are talked about in the help page :h |map.txt|. Use > 610 :help mapmode-i 611 < to find out about the |:imap| command. Also use :map-topic 612 to find out about certain subtopics particular for mappings. e.g: > 613 :help :map-local 614 < for buffer-local mappings or > 615 :help map-bar 616 < for how the '|' is handled in mappings. 617 618 15) Command definitions are talked about :h command-topic, so use > 619 :help command-bang 620 < to find out about the '!' argument for custom commands. 621 622 16) Window management commands always start with CTRL-W, so you find the 623 corresponding help at :h CTRL-W_letter. E.g. > 624 :help CTRL-W_p 625 < for moving the previous accessed window. You can also access > 626 :help windows.txt 627 < and read your way through if you are looking for window handling 628 commands. 629 630 17) Use |:helpgrep| to search in all help pages (and also of any installed 631 plugins). See |:helpgrep| for how to use it. 632 To search for a topic: > 633 :helpgrep topic 634 < This takes you to the first match. To go to the next one: > 635 :cnext 636 < All matches are available in the quickfix window which can be opened 637 with: > 638 :copen 639 < Move around to the match you like and press Enter to jump to that help. 640 641 18) The user manual. This describes help topics for beginners in a rather 642 friendly way. Start at |usr_toc.txt| to find the table of content (as you 643 might have guessed): > 644 :help usr_toc.txt 645 < Skim over the contents to find interesting topics. The "Digraphs" and 646 "Entering special characters" items are in chapter 24, so to go to that 647 particular help page: > 648 :help usr_24.txt 649 < Also if you want to access a certain chapter in the help, the chapter 650 number can be accessed directly like this: > 651 :help 10.1 652 < which goes to chapter 10.1 in |usr_10.txt| and talks about recording 653 macros. 654 655 19) Highlighting groups. Always start with hl-groupname. E.g. > 656 :help hl-WarningMsg 657 < talks about the WarningMsg highlighting group. 658 659 20) Syntax highlighting is namespaced to :syn-topic. E.g. > 660 :help :syn-conceal 661 < talks about the conceal argument for the ":syn" command. 662 663 21) Quickfix commands usually start with :c while location list commands 664 usually start with :l 665 666 22) Autocommand events can be found by their name: > 667 :help BufWinLeave 668 < To see all possible events: > 669 :help autocommand-events 670 671 23) Command-line switches always start with "-". So for the help of the -f 672 command switch of Vim use: > 673 :help -f 674 675 24) Optional features always start with "+". To find out about the 676 conceal feature use: > 677 :help +conceal 678 679 25) Documentation for included filetype specific functionality is usually 680 available in the form ft-<filetype>-<functionality>. So > 681 :help ft-c-syntax 682 < talks about the C syntax file and the option it provides. Sometimes, 683 additional sections for omni completion > 684 :help ft-php-omni 685 < or filetype plugins > 686 :help ft-tex-plugin 687 < are available. 688 689 26) Error and Warning codes can be looked up directly in the help. So > 690 :help E297 691 < takes you exactly to the description of the swap error message and > 692 :help W10 693 < talks about the warning "Changing a readonly file". 694 Sometimes, however, those error codes are not described, but rather are 695 listed at the Vim command that usually causes this. So: > 696 :help E128 697 < takes you to the |:function| command 698 699 27) Documentation for packages distributed with Vim have the form 700 package-<name>. So > 701 :help package-comment 702 < 703 will bring you to the help section for the included comment plugin and how 704 to enable it. 705 706 707 ============================================================================== 708 709 Next chapter: |usr_03.txt| Moving around 710 711 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: