codekingpro/portable-devtools

1*usr_02.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		     VIM USER MANUAL	by Bram Moolenaar5 6 7			    The first steps in Vim8 9 10This chapter provides just enough information to edit a file with Vim.  Not11well or fast, but you can edit.  Take some time to practice with these12commands, they form the base for what follows.13 14|02.1|	Running Vim for the First Time15|02.2|	Inserting text16|02.3|	Moving around17|02.4|	Deleting characters18|02.5|	Undo and Redo19|02.6|	Other editing commands20|02.7|	Getting out21|02.8|	Finding help22 23     Next chapter: |usr_03.txt|  Moving around24 Previous chapter: |usr_01.txt|  About the manuals25Table of contents: |usr_toc.txt|26 27==============================================================================28*02.1*	Running Vim for the First Time29 30To start Vim, enter this command: >31 32	gvim file.txt33 34In UNIX you can type this at any command prompt.  If you are running Microsoft35Windows, open a Command Prompt and enter the command.36   In either case, Vim starts editing a file called file.txt.  Because this37is a new file, you get a blank window.  This is what your screen will look38like:39 40	+---------------------------------------+41	|#					|42	|~					|43	|~					|44	|~					|45	|~					|46	|"file.txt" [New file]			|47	+---------------------------------------+48		('#' is the cursor position.)49 50The tilde (~) lines indicate lines not in the file.  In other words, when Vim51runs out of file to display, it displays tilde lines.  At the bottom of the52screen, a message line indicates the file is named file.txt and shows that you53are creating a new file.  The message information is temporary and other54information overwrites it.55 56 57THE VIM COMMAND58 59The gvim command causes the editor to create a new window for editing.  If you60use this command: >61 62	vim file.txt63 64the editing occurs inside your command window.  In other words, if you are65running inside an xterm, the editor uses your xterm window.  If you are using66an MS-Windows command prompt window, the editing occurs inside this window.67The text in the window will look the same for both versions, but with gvim you68have extra features, like a menu bar.  More about that later.69 70==============================================================================71*02.2*	Inserting text72 73The Vim editor is a modal editor.  That means that the editor behaves74differently, depending on which mode you are in.  The two basic modes are75called Normal mode and Insert mode.  In Normal mode the characters you type76are 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 Insert78mode you type the "i" command (i for Insert).  Then you can enter79the text.  It will be inserted into the file.  Do not worry if you make80mistakes; you can correct them later.  To enter the following programmer's81limerick, this is what you type: >82 83	iA very intelligent turtle84	Found programming UNIX a hurdle85 86After typing "turtle" you press the <Enter> key to start a new line.  Finally87you press the <Esc> key to stop Insert mode and go back to Normal mode.  You88now 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 99WHAT IS THE MODE?100 101To be able to see what mode you are in, type this command: >102 103	:set showmode104 105You will notice that when typing the colon Vim moves the cursor to the last106line of the window.  That's where you type colon commands (commands that start107with a colon).  Finish this command by pressing the <Enter> key (all commands108that start with a colon are finished this way).109   Now, if you type the "i" command Vim will display --INSERT-- at the bottom110of 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 120If you press <Esc> to go back to Normal mode the last line will be made blank.121 122 123GETTING OUT OF TROUBLE124 125One of the problems for Vim novices is mode confusion, which is caused by126forgetting which mode you are in or by accidentally typing a command that127switches modes.  To get back to Normal mode, no matter what mode you are in,128press the <Esc> key.  Sometimes you have to press it twice.  If Vim beeps back129at you, you already are in Normal mode.130 131==============================================================================132*02.3*	Moving around133 134After you return to Normal mode, you can move around by using these keys:135 136	h   left						*hjkl*137	j   down138	k   up139	l   right140 141At first, it may appear that these commands were chosen at random.  After all,142who ever heard of using l for right?  But actually, there is a very good143reason for these choices: Moving the cursor is the most common thing you do in144an editor, and these keys are on the home row of your right hand.  In other145words, these commands are placed where you can type them the fastest146(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 arrow151	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, this153	can take a significant amount of time.154	   Also, there are keyboards which do not have arrow keys, or which155	locate them in unusual places; therefore, knowing the use of the hjkl156	keys helps in those situations.157 158One way to remember these commands is that h is on the left, l is on the159right and j points down.  In a picture: >160 161		       k162		   h     l163		     j164 165The best way to learn these commands is by using them.  Use the "i" command to166insert some more lines of text.  Then use the hjkl keys to move around and167insert a word somewhere.  Don't forget to press <Esc> to go back to Normal168mode.  The |vimtutor| is also a nice way to learn by doing.169 170For Japanese users, Hiroshi Iwatani suggested using this:171 172			Komsomolsk173			    ^174			    |175	   Huan Ho	<--- --->  Los Angeles176	(Yellow river)	    |177			    v178			  Java (the island, not the programming language)179 180==============================================================================181*02.4*	Deleting characters182 183To delete a character, move the cursor over it and type "x".  (This is a184throwback to the old days of the typewriter, when you deleted things by typing185xxxx over them.)  Move the cursor to the beginning of the first line, for186example, and type xxxxxxx (seven x's) to delete "A very ".  The result should187look like this:188 189	+---------------------------------------+190	|intelligent turtle			|191	|Found programming UNIX a hurdle	|192	|~					|193	|~					|194	|					|195	+---------------------------------------+196 197Now you can insert new text, for example by typing: >198 199	iA young <Esc>200 201This begins an insert (the i), inserts the words "A young", and then exits202insert 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 213DELETING A LINE214 215To delete a whole line use the "dd" command.  The following line will216then move up to fill the gap:217 218	+---------------------------------------+219	|Found programming UNIX a hurdle	|220	|~					|221	|~					|222	|~					|223	|					|224	+---------------------------------------+225 226 227DELETING A LINE BREAK228 229In Vim you can join two lines together, which means that the line break230between them is deleted.  The "J" command does this.231   Take these two lines:232 233	A young intelligent ~234	turtle ~235 236Move the cursor to the first line and press "J":237 238	A young intelligent turtle ~239 240==============================================================================241*02.5*	Undo and Redo242 243Suppose you delete too much.  Well, you can type it in again, but an easier244way exists.  The "u" command undoes the last edit.  Take a look at this in245action: 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 250Now type xxxxxxx to delete "A young".  The result is as follows:251 252	 intelligent turtle ~253 254Type "u" to undo the last delete.  That delete removed the g, so the undo255restores the character.256 257	g intelligent turtle ~258 259The next "u" command restores the next-to-last character deleted:260 261	ng intelligent turtle ~262 263The 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 text273	back, you have Vim configured to work Vi compatible.  Look here to fix274	this: |not-compatible|.275	   This text assumes you work "The Vim Way".  You might prefer to use276	the good old Vi way, but you will have to watch out for small277	differences in the text then.278 279 280REDO281 282If you undo too many times, you can press CTRL-R (redo) to reverse the283preceding command.  In other words, it undoes the undo.  To see this in284action, press CTRL-R twice.  The character A and the space after it disappear:285 286	young intelligent turtle ~287 288There's a special version of the undo command, the "U" (undo line) command.289The undo line command undoes all the changes made on the last line that was290edited.  Typing this command twice cancels the preceding "U".291 292	A very intelligent turtle ~293	  xxxx				Delete very294 295	A intelligent turtle ~296		      xxxxxx		Delete turtle297 298	A intelligent ~299					Restore line with "U"300	A very intelligent turtle ~301					Undo "U" with "u"302	A intelligent ~303 304The "U" command is a change by itself, which the "u" command undoes and CTRL-R305redoes.  This might be a bit confusing.  Don't worry, with "u" and CTRL-R you306can go to any of the situations you had.  More about that in section |32.2|.307 308==============================================================================309*02.6*	Other editing commands310 311Vim has a large number of commands to change the text.  See |Q_in| and below.312Here are a few often used ones.313 314 315APPENDING316 317The "i" command inserts a character before the character under the cursor.318That works fine; but what happens if you want to add stuff to the end of the319line?  For that you need to insert text after the cursor.  This is done with320the "a" (append) command.321   For example, to change the line322 323	and that's not saying much for the turtle. ~324to325	and that's not saying much for the turtle!!! ~326 327move the cursor over to the dot at the end of the line.  Then type "x" to328delete the period.  The cursor is now positioned at the end of the line on the329e in turtle.  Now type >330 331	a!!!<Esc>332 333to append three exclamation points after the e in turtle:334 335	and that's not saying much for the turtle!!! ~336 337 338OPENING UP A NEW LINE339 340The "o" command creates a new, empty line below the cursor and puts Vim in341Insert 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 347If you now use the "o" command and type new text: >348 349	oThat liked using Vim<Esc>350 351The result is:352 353	A very intelligent turtle ~354	That liked using Vim ~355	Found programming UNIX a hurdle ~356 357The "O" command (uppercase) opens a line above the cursor.358 359 360USING A COUNT361 362Suppose you want to move up nine lines.  You can type "kkkkkkkkk" or you can363enter the command "9k".  In fact, you can precede many commands with a number.364Earlier in this chapter, for instance, you added three exclamation points to365the end of a line by typing "a!!!<Esc>".  Another way to do this is to use the366command "3a!<Esc>".  The count of 3 tells the command that follows to triple367its effect.  Similarly, to delete three characters, use the command "3x".  The368count always comes before the command it applies to.369 370==============================================================================371*02.7*	Getting out372 373To 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 backup377	file.  If you type "ZZ", your changes are committed and there's no378	turning back.  You can configure the Vim editor to produce backup379	files; see |07.4|.380 381 382DISCARDING CHANGES383 384Sometimes you will make a sequence of changes and suddenly realize you were385better off before you started.  Not to worry; Vim has a386quit-and-throw-things-away command.  It is: >387 388	:q!389 390Don't forget to press <Enter> to finish the command.391 392For those of you interested in the details, the three parts of this command393are the colon (:), which enters Command-line mode; the q command, which tells394the editor to quit; and the override command modifier (!).395   The override command modifier is needed because Vim is reluctant to throw396away changes.  If you were to just type ":q", Vim would display an error397message and refuse to exit:398 399	E37: No write since last change (use ! to override) ~400 401By specifying the override, you are in effect telling Vim, "I know that what402I'm doing looks stupid, but I really want to do this."403 404If you want to continue editing with Vim: The ":e!" command reloads the405original version of the file.406 407==============================================================================408*02.8*	Finding help409 410Everything you always wanted to know can be found in the Vim help files.411Don't be afraid to ask!412 413If you know what you are looking for, it is usually easier to search for it414using the help system, instead of using Google.  Because the subjects follow415a certain style guide.416 417Also the help has the advantage of belonging to your particular Vim version.418You won't see help for commands added later.  These would not work for you.419 420To get generic help use this command: >421 422	:help423 424You could also use the first function key <F1>.  If your keyboard has a <Help>425key it might work as well.426   If you don't supply a subject, ":help" displays the general help window.427The creators of Vim did something very clever (or very lazy) with the help428system: They made the help window a normal editing window.  You can use all429the normal Vim commands to move through the help information.  Therefore h, j,430k, 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 of432the editor: "ZZ".  This will only close the help window, not exit Vim.433 434As you read the help text, you will notice some text enclosed in vertical bars435(for example, |help|).  This indicates a hyperlink.  If you position the436cursor anywhere between the bars and press CTRL-] (jump to tag), the help437system takes you to the indicated subject.  (For reasons not discussed here,438the Vim terminology for a hyperlink is tag.  So CTRL-] jumps to the location439of 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 you441back to the preceding position.  CTRL-O (jump to older position) also works442nicely here.443   At the top of the help screen, there is the notation "*help.txt*".  This444name between "*" characters is used by the help system to define a tag445(hyperlink destination).446   See |29.1| for details about using tags.447 448To get help on a given subject, use the following command: >449 450	:help {subject}451 452To get help on the "x" command, for example, enter the following: >453 454	:help x455 456To find out how to delete text, use this command: >457 458	:help deleting459 460To get a complete index of all Vim commands, use the following command: >461 462	:help index463 464When you need to get help for a control character command (for example,465CTRL-A), you need to spell it with the prefix "CTRL-". >466 467	:help CTRL-A468 469The Vim editor has many different modes.  By default, the help system displays470the normal-mode commands.  For example, the following command displays help471for the normal-mode CTRL-H command: >472 473	:help CTRL-H474 475To identify other modes, use a mode prefix.  If you want the help for the476insert-mode version of a command, use "i_".  For CTRL-H this gives you the477following command: >478 479	:help i_CTRL-H480 481When you start the Vim editor, you can use several command-line arguments.482These all begin with a dash (-).  To find what the -t argument does, for483example, use the command: >484 485	:help -t486 487The Vim editor has a number of options that enable you to configure and488customize the editor.  If you want help for an option, you need to enclose it489in single quotation marks.  To find out what the 'number' option does, for490example, use the following command: >491 492	:help 'number'493 494The table with all mode prefixes can be found below: |help-summary|.495 496Special keys are enclosed in angle brackets.  To find help on the up-arrow key497in Insert mode, for instance, use this command: >498 499	:help i_<Up>500 501If you see an error message that you don't understand, for example:502 503	E37: No write since last change (use ! to override) ~504 505You can use the error ID at the start to find help about it: >506 507	:help E37508 509 510Summary:					*help-summary*  >511 5121) 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 helphelp517 5182) Follow the links in bars to related help.  You can go from the detailed519   help to the user documentation, which describes certain commands more from520   a user perspective and less detailed.  E.g. after: >521	:help pattern.txt522<   You can see the user guide topics |03.9| and |usr_27.txt| in the523   introduction.524 5253) Options are enclosed in single apostrophes.  To go to the help topic for526   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.txt530<   to open the help page which describes all option handling and then search531   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 5404) Normal mode commands do not have a prefix.  To go to the help page for the541   "gt" command: >542	:help gt543 5445) Insert mode commands start with i_.  Help for deleting a word: >545	:help i_CTRL-W546 5476) Visual mode commands start with v_.  Help for jumping to the other side of548   the Visual area: >549	:help v_o550 5517) Command line editing and arguments start with c_.  Help for using the552   command argument %: >553	:help c_%554 5558) Ex-commands always start with ":", so to go to the ":s" command help: >556	:help :s557 5589) Commands specifically for debugging start with ">".  To go to the help559   for the "cont" debug command: >560	:help >cont561 56210) Key combinations.  They usually start with a single letter indicating563    the mode for which they can be used.  E.g.: >564	:help i_CTRL-X565<    takes you to the family of CTRL-X commands for insert mode which can be566    used to auto-complete different things.  Note, that certain keys will567    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 at569    :h CTRL-<Letter>. E.g.  >570	:help CTRL-W571<    In contrast >572	:help c_CTRL-R573<    will describe what the CTRL-R does when entering commands in the Command574    line and >575	:help v_CTRL-A576<    talks about incrementing numbers in visual mode and >577	:help g_CTRL-A578<    talks about the "g<C-A>" command (e.g. you have to press "g" then579    <CTRL-A>).  Here the "g" stands for the normal command "g" which always580    expects a second key before doing something similar to the commands581    starting with "z".582 58311) Regexp items always start with /.  So to get help for the "\+" quantifier584    in Vim regexes: >585	:help /\+586<    If you need to know everything about regular expressions, start reading587    at: >588	:help pattern.txt589 59012) Registers always start with "quote".  To find out about the special ":"591    register: >592	:help quote:593 59413) Vim script is available at >595	:help eval.txt596<    Certain aspects of the language are available at :h expr-X where "X" is a597    single letter. E.g.  >598	:help expr-!599<    will take you to the topic describing the "!" (Not) operator for Vim600    script.601    Also important is >602	:help function-list603<    to find a short description of all functions available.  Help topics for604    Vim script functions always include the "()", so: >605	:help append()606<    talks about the append Vim script function rather than how to append text607    in the current buffer.608 60914) Mappings are talked about in the help page :h |map.txt|.  Use >610	:help mapmode-i611<    to find out about the |:imap| command.  Also use :map-topic612    to find out about certain subtopics particular for mappings.  e.g: >613	:help :map-local614<    for buffer-local mappings or >615	:help map-bar616<    for how the '|' is handled in mappings.617 61815) Command definitions are talked about :h command-topic, so use >619	:help command-bang620<    to find out about the '!' argument for custom commands.621 62216) Window management commands always start with CTRL-W, so you find the623    corresponding help at :h CTRL-W_letter.  E.g. >624	:help CTRL-W_p625<    for moving the previous accessed window.  You can also access >626	:help windows.txt627<    and read your way through if you are looking for window handling628    commands.629 63017) Use |:helpgrep| to search in all help pages (and also of any installed631    plugins).  See |:helpgrep| for how to use it.632    To search for a topic: >633	:helpgrep topic634<    This takes you to the first match.  To go to the next one: >635	:cnext636<    All matches are available in the quickfix window which can be opened637    with: >638	:copen639<    Move around to the match you like and press Enter to jump to that help.640 64118) The user manual.  This describes help topics for beginners in a rather642    friendly way.  Start at |usr_toc.txt| to find the table of content (as you643    might have guessed): >644	:help usr_toc.txt645<    Skim over the contents to find interesting topics.  The "Digraphs" and646    "Entering special characters" items are in chapter 24, so to go to that647    particular help page: >648	:help usr_24.txt649<    Also if you want to access a certain chapter in the help, the chapter650    number can be accessed directly like this: >651	:help 10.1652<    which goes to chapter 10.1 in |usr_10.txt| and talks about recording653    macros.654 65519) Highlighting groups.  Always start with hl-groupname.  E.g. >656	:help hl-WarningMsg657<    talks about the WarningMsg highlighting group.658 65920) Syntax highlighting is namespaced to :syn-topic.  E.g. >660	:help :syn-conceal661<    talks about the conceal argument for the ":syn" command.662 66321) Quickfix commands usually start with :c while location list commands664    usually start with :l665 66622) Autocommand events can be found by their name: >667	:help BufWinLeave668<    To see all possible events: >669	:help autocommand-events670 67123) Command-line switches always start with "-".  So for the help of the -f672    command switch of Vim use: >673	:help -f674 67524) Optional features always start with "+".  To find out about the676    conceal feature use: >677	:help +conceal678 67925) Documentation for included filetype specific functionality is usually680    available in the form ft-<filetype>-<functionality>.  So >681	:help ft-c-syntax682<    talks about the C syntax file and the option it provides.  Sometimes,683    additional sections for omni completion >684	:help ft-php-omni685<    or filetype plugins >686	:help ft-tex-plugin687<    are available.688 68926) Error and Warning codes can be looked up directly in the help.  So >690	:help E297691<    takes you exactly to the description of the swap error message and >692	:help W10693<    talks about the warning "Changing a readonly file".694    Sometimes, however, those error codes are not described, but rather are695    listed at the Vim command that usually causes this.  So: >696	:help E128697<    takes you to the |:function| command698 69927) Documentation for packages distributed with Vim have the form700     package-<name>. So >701	:help package-comment702<703    will bring you to the help section for the included comment plugin and how704    to enable it.705 706 707==============================================================================708 709Next chapter: |usr_03.txt|  Moving around710 711Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl:712