codekingpro/portable-devtools
114k
1*insert.txt* For Vim version 9.2. Last change: 2026 Feb 142 3 4 VIM REFERENCE MANUAL by Bram Moolenaar5 6 7 *Insert* *Insert-mode*8Inserting and replacing text *mode-ins-repl*9 10Most of this file is about Insert and Replace mode. At the end are a few11commands for inserting text in other ways.12 13An overview of the most often used commands can be found in chapter 24 of the14user manual |usr_24.txt|.15 161. Special keys |ins-special-keys|172. Special special keys |ins-special-special|183. 'textwidth' and 'wrapmargin' options |ins-textwidth|194. 'expandtab', 'smarttab' and 'softtabstop' options |ins-expandtab|205. Replace mode |Replace-mode|216. Virtual Replace mode |Virtual-Replace-mode|227. Insert mode completion |ins-completion|238. Insert mode commands |inserting|249. Ex insert commands |inserting-ex|2510. Inserting a file |inserting-file|26 27Also see 'virtualedit', for moving the cursor to positions where there is no28character. Useful for editing a table.29 30==============================================================================311. Special keys *ins-special-keys*32 33In Insert and Replace mode, the following characters have a special meaning;34other characters are inserted directly. To insert one of these special35characters into the buffer, precede it with CTRL-V. To insert a <Nul>36character use "CTRL-V CTRL-@" or "CTRL-V 000". On some systems, you have to37use "CTRL-V 003" to insert a CTRL-C. Note: When CTRL-V is mapped you can38often use CTRL-Q instead |i_CTRL-Q|.39 40If you are working in a special language mode when inserting text, see the41'langmap' option, 'langmap', on how to avoid switching this mode on and off42all the time.43 44If you have 'insertmode' set, <Esc> and a few other keys get another meaning.45See 'insertmode'.46 47char action ~48-----------------------------------------------------------------------49 *i_CTRL-[* *i_<Esc>*50<Esc> or CTRL-[ End insert or Replace mode, go back to Normal mode. Finish51 abbreviation.52 Note: If your <Esc> key is hard to hit on your keyboard, train53 yourself to use CTRL-[.54 If Esc doesn't work and you are using a Mac, try CTRL-<Esc>.55 Or disable Listening under Accessibility preferences.56 *i_CTRL-C*57CTRL-C Quit insert mode, go back to Normal mode. Do not check for58 abbreviations. Does not trigger the |InsertLeave| autocommand59 event.60 61 *i_CTRL-@*62CTRL-@ Insert previously inserted text and stop insert.63 64 *i_CTRL-A*65CTRL-A Insert previously inserted text.66 67 *i_CTRL-H* *i_<BS>* *i_BS*68<BS> or CTRL-H Delete the character before the cursor (see |i_backspacing|69 about joining lines).70 See |:fixdel| if your <BS> key does not do what you want.71 72 *i_<Del>* *i_DEL*73<Del> Delete the character under the cursor. If the cursor is at74 the end of the line, and the 'backspace' option includes75 "eol", delete the <EOL>; the next line is appended after the76 current one.77 See |:fixdel| if your <Del> key does not do what you want.78 *i_CTRL-W*79CTRL-W Delete the word before the cursor (see |i_backspacing| about80 joining lines). See the section "word motions",81 |word-motions|, for the definition of a word.82 *i_CTRL-U*83CTRL-U Delete all characters that were entered after starting Insert84 mode and before the cursor in the current line.85 If there are no newly entered characters and 'backspace' is86 not empty, delete all characters before the cursor in the87 current line.88 If C-indenting is enabled the indent will be adjusted if the89 line becomes blank.90 See |i_backspacing| about joining lines.91 *i_CTRL-I* *i_<Tab>* *i_Tab*92<Tab> or CTRL-I Insert a tab. If the 'expandtab' option is on, the93 equivalent number of spaces is inserted (use CTRL-V <Tab> to94 avoid the expansion; use CTRL-Q <Tab> if CTRL-V is mapped95 |i_CTRL-Q|). See also the 'smarttab' option and96 |ins-expandtab|.97 *i_CTRL-J* *i_<NL>*98<NL> or CTRL-J Begin new line.99 *i_CTRL-M* *i_<CR>*100<CR> or CTRL-M Begin new line.101 *i_CTRL-K*102CTRL-K {char1} [char2]103 Enter digraph (see |digraphs|). When {char1} is a special104 key, the code for that key is inserted in <> form. For105 example, the string "<S-Space>" can be entered by typing106 <C-K><S-Space> (two keys). Neither char is considered for107 mapping.108 109CTRL-N Find next keyword (see |i_CTRL-N|).110CTRL-P Find previous keyword (see |i_CTRL-P|).111 112CTRL-R {register} *i_CTRL-R*113 Insert the contents of a register. Between typing CTRL-R and114 the second character, '"' will be displayed to indicate that115 you are expected to enter the name of a register.116 The text is inserted as if you typed it, but mappings and117 abbreviations are not used. If you have options like118 'textwidth', 'formatoptions', or 'autoindent' set, this will119 influence what will be inserted. This is different from what120 happens with the "p" command and pasting with the mouse.121 Special registers:122 '"' the unnamed register, containing the text of123 the last delete or yank124 '%' the current file name125 '#' the alternate file name126 '*' the clipboard contents (X11: primary selection)127 '+' the clipboard contents128 '/' the last search pattern129 ':' the last command-line130 '.' the last inserted text131 *i_CTRL-R_-*132 '-' the last small (less than a line) delete133 register. This is repeatable using |.| since134 it remembers the register to put instead of135 the literal text to insert.136 *i_CTRL-R_=*137 '=' the expression register: you are prompted to138 enter an expression (see |expression|)139 Note that 0x80 (128 decimal) is used for140 special keys. E.g., you can use this to move141 the cursor up:142 CTRL-R ="\<Up>"143 Use CTRL-R CTRL-R to insert text literally.144 When the result is a |List| the items are used145 as lines. They can have line breaks inside146 too.147 When the result is a Float it's automatically148 converted to a String.149 When append() or setline() is invoked the undo150 sequence will be broken.151 See |registers| about registers.152 153CTRL-R CTRL-R {register} *i_CTRL-R_CTRL-R*154 Insert the contents of a register. Works like using a single155 CTRL-R, but the text is inserted literally, not as if typed.156 This differs when the register contains characters like <BS>.157 Example, where register a contains "ab^Hc": >158 CTRL-R a results in "ac".159 CTRL-R CTRL-R a results in "ab^Hc".160< Options 'textwidth', 'formatoptions', etc. still apply. If161 you also want to avoid these, use CTRL-R CTRL-O, see below.162 The '.' register (last inserted text) is still inserted as163 typed.164 After this command, the '.' register contains the text from165 the register as if it was inserted by typing it.166 167CTRL-R CTRL-O {register} *i_CTRL-R_CTRL-O*168 Insert the contents of a register literally and don't169 auto-indent. Does the same as pasting with the mouse170 |<MiddleMouse>|. When the register is linewise this will171 insert the text above the current line, like with `P`.172 The '.' register (last inserted text) is still inserted as173 typed.174 After this command, the '.' register contains the command175 typed and not the text. I.e., the literals "^R^O" and not the176 text from the register.177 Does not replace characters in |Replace-mode|!178 179CTRL-R CTRL-P {register} *i_CTRL-R_CTRL-P*180 Insert the contents of a register literally and fix the181 indent, like |[<MiddleMouse>|.182 The '.' register (last inserted text) is still inserted as183 typed.184 After this command, the '.' register contains the command185 typed and not the text. I.e., the literals "^R^P" and not the186 text from the register.187 Does not replace characters in |Replace-mode|!188 189 *i_CTRL-T*190CTRL-T Insert one shiftwidth of indent at the start of the current191 line. The indent is always rounded to a 'shiftwidth' (this is192 vi compatible).193 *i_CTRL-D*194CTRL-D Delete one shiftwidth of indent at the start of the current195 line. The indent is always rounded to a 'shiftwidth' (this is196 vi compatible).197 *i_0_CTRL-D*1980 CTRL-D Delete all indent in the current line.199 200 *i_^_CTRL-D*201^ CTRL-D Delete all indent in the current line. The indent is202 restored in the next line. This is useful when inserting a203 label.204 205 *i_CTRL-V*206CTRL-V Insert next non-digit literally. For special keys, the207 terminal code is inserted. It's also possible to enter the208 decimal, octal or hexadecimal value of a character209 |i_CTRL-V_digit|.210 The characters typed right after CTRL-V are not considered for211 mapping.212 Note: When CTRL-V is mapped (e.g., to paste text) you can213 often use CTRL-Q instead |i_CTRL-Q|.214 When |modifyOtherKeys| is enabled then special Escape sequence215 is converted back to what it was without |modifyOtherKeys|,216 unless the Shift key is also pressed.217 218 *i_CTRL-Q*219CTRL-Q Same as CTRL-V.220 Note: Some terminal connections may eat CTRL-Q, it doesn't221 work then. It does work in the GUI.222 223CTRL-SHIFT-V *i_CTRL-SHIFT-V* *i_CTRL-SHIFT-Q*224CTRL-SHIFT-Q Works just like CTRL-V, unless |modifyOtherKeys| is active,225 then it inserts the Escape sequence for a key with modifiers.226 Note: When CTRL-SHIFT-V is intercepted by your system (e.g.,227 to paste text) you can often use CTRL-SHIFT-Q instead.228 However, in some terminals (e.g. GNOME Terminal), CTRL-SHIFT-Q229 quits the terminal without confirmation.230 231CTRL-X Enter CTRL-X mode. This is a sub-mode where commands can232 be given to complete words or scroll the window. See233 |i_CTRL-X| and |ins-completion|.234 235 *i_CTRL-E*236CTRL-E Insert the character which is below the cursor.237 *i_CTRL-Y*238CTRL-Y Insert the character which is above the cursor.239 Note that for CTRL-E and CTRL-Y 'textwidth' is not used, to be240 able to copy characters from a long line.241 242 *i_CTRL-_*243CTRL-_ Switch between languages, as follows:244 - When in a rightleft window, revins and nohkmap are toggled,245 since English will likely be inserted in this case.246 - When in a norightleft window, revins and hkmap are toggled,247 since Hebrew will likely be inserted in this case.248 249 CTRL-_ moves the cursor to the end of the typed text.250 251 This command is only available when the 'allowrevins' option252 is set.253 Please refer to |rileft.txt| for more information about254 right-to-left mode.255 Only if compiled with the |+rightleft| feature.256 257 *i_CTRL-^*258CTRL-^ Toggle the use of typing language characters.259 When language |:lmap| mappings are defined:260 - If 'iminsert' is 1 (langmap mappings used) it becomes 0 (no261 langmap mappings used).262 - If 'iminsert' has another value it becomes 1, thus langmap263 mappings are enabled.264 When no language mappings are defined:265 - If 'iminsert' is 2 (Input Method used) it becomes 0 (no266 Input Method used).267 - If 'iminsert' has another value it becomes 2, thus the Input268 Method is enabled.269 When set to 1, the value of the "b:keymap_name" variable, the270 'keymap' option or "<lang>" appears in the status line.271 The language mappings are normally used to type characters272 that are different from what the keyboard produces. The273 'keymap' option can be used to install a whole number of them.274 275 *i_CTRL-]*276CTRL-] Trigger abbreviation, without inserting a character.277 278 *i_<Insert>*279<Insert> Toggle between Insert and Replace mode.280-----------------------------------------------------------------------281 282 *i_backspacing*283The effect of the <BS>, CTRL-W, and CTRL-U depend on the 'backspace' option284(unless 'revins' is set). This is a comma-separated list of items:285 286item action ~287indent allow backspacing over autoindent288eol allow backspacing over line breaks (join lines)289start allow backspacing over the start of insert; CTRL-W and CTRL-U stop290 once at the start of insert.291nostop like start, except CTRL-W and CTRL-U do not stop at the start of292 insert.293 294When 'backspace' is empty, Vi compatible backspacing is used. You cannot295backspace over autoindent, before column 1 or before where insert started.296 297For backwards compatibility the values "0", "1", "2" and "3" are also allowed,298see 'backspace'.299 300If the 'backspace' option does contain "eol" and the cursor is in column 1301when one of the three keys is used, the current line is joined with the302previous line. This effectively deletes the <EOL> in front of the cursor.303 304 *i_CTRL-V_digit*305With CTRL-V the decimal, octal or hexadecimal value of a character can be306entered directly. This way you can enter any character, except a line break307(<NL>, value 10). There are five ways to enter the character value:308 309first char mode max nr of chars max value ~310(none) decimal 3 255311o or O octal 3 377 (255)312x or X hexadecimal 2 ff (255)313u hexadecimal 4 ffff (65535)314U hexadecimal 8 7fffffff (2147483647)315 316Normally you would type the maximum number of characters. Thus to enter a317space (value 32) you would type <C-V>032. You can omit the leading zero, in318which case the character typed after the number must be a non-digit. This319happens for the other modes as well: As soon as you type a character that is320invalid for the mode, the value before it will be used and the "invalid"321character is dealt with in the normal way.322 323If you enter a value of 10, it will end up in the file as a 0. The 10 is a324<NL>, which is used internally to represent the <Nul> character. When writing325the buffer to a file, the <NL> character is translated into <Nul>. The <NL>326character is written at the end of each line. Thus if you want to insert a327<NL> character in a file you will have to make a line break.328Also see 'fileformat'.329 330 *i_CTRL-X* *insert_expand*331CTRL-X enters a sub-mode where several commands can be used. Most of these332commands do keyword completion; see |ins-completion|.333 334Two commands can be used to scroll the window up or down, without exiting335insert mode:336 337 *i_CTRL-X_CTRL-E*338CTRL-X CTRL-E scroll window one line up.339 When doing completion look here: |complete_CTRL-E|340 341 *i_CTRL-X_CTRL-Y*342CTRL-X CTRL-Y scroll window one line down.343 When doing completion look here: |complete_CTRL-Y|344 345After CTRL-X is pressed, each CTRL-E (CTRL-Y) scrolls the window up (down) by346one line unless that would cause the cursor to move from its current position347in the file. As soon as another key is pressed, CTRL-X mode is exited and348that key is interpreted as in Insert mode.349 350 351==============================================================================3522. Special special keys *ins-special-special*353 354The following keys are special. They stop the current insert, do something,355and then restart insertion. This means you can do something without getting356out of Insert mode. This is very handy if you prefer to use the Insert mode357all the time, just like editors that don't have a separate Normal mode. You358may also want to set the 'backspace' option to "indent,eol,start" and set the359'insertmode' option. You can use CTRL-O if you want to map a function key to360a command.361 362The changes (inserted or deleted characters) before and after these keys can363be undone separately. Only the last change can be redone and always behaves364like an "i" command.365 366char action ~367-----------------------------------------------------------------------368<Up> cursor one line up *i_<Up>*369<Down> cursor one line down *i_<Down>*370CTRL-G <Up> cursor one line up, insert start column *i_CTRL-G_<Up>*371CTRL-G k cursor one line up, insert start column *i_CTRL-G_k*372CTRL-G CTRL-K cursor one line up, insert start column *i_CTRL-G_CTRL-K*373CTRL-G <Down> cursor one line down, insert start column *i_CTRL-G_<Down>*374CTRL-G j cursor one line down, insert start column *i_CTRL-G_j*375CTRL-G CTRL-J cursor one line down, insert start column *i_CTRL-G_CTRL-J*376<Left> cursor one character left *i_<Left>*377<Right> cursor one character right *i_<Right>*378<S-Left> cursor one word back (like "b" command) *i_<S-Left>*379<C-Left> cursor one word back (like "b" command) *i_<C-Left>*380<S-Right> cursor one word forward (like "w" command) *i_<S-Right>*381<C-Right> cursor one word forward (like "w" command) *i_<C-Right>*382<Home> cursor to first char in the line *i_<Home>*383<End> cursor to after last char in the line *i_<End>*384<C-Home> cursor to first char in the file *i_<C-Home>*385<C-End> cursor to after last char in the file *i_<C-End>*386<LeftMouse> cursor to position of mouse click *i_<LeftMouse>*387<S-Up> move window one page up *i_<S-Up>*388<PageUp> move window one page up *i_<PageUp>*389<S-Down> move window one page down *i_<S-Down>*390<PageDown> move window one page down *i_<PageDown>*391<ScrollWheelDown> move window three lines down *i_<ScrollWheelDown>*392<S-ScrollWheelDown> move window one page down *i_<S-ScrollWheelDown>*393<ScrollWheelUp> move window three lines up *i_<ScrollWheelUp>*394<S-ScrollWheelUp> move window one page up *i_<S-ScrollWheelUp>*395<ScrollWheelLeft> move window six columns left *i_<ScrollWheelLeft>*396<S-ScrollWheelLeft> move window one page left *i_<S-ScrollWheelLeft>*397<ScrollWheelRight> move window six columns right *i_<ScrollWheelRight>*398<S-ScrollWheelRight> move window one page right *i_<S-ScrollWheelRight>*399CTRL-O execute one command, return to Insert mode *i_CTRL-O*400CTRL-\ CTRL-O like CTRL-O but don't move the cursor *i_CTRL-\_CTRL-O*401CTRL-L when 'insertmode' is set: go to Normal mode *i_CTRL-L*402CTRL-G u close undo sequence, start new change *i_CTRL-G_u*403CTRL-G U don't start a new undo block with the next *i_CTRL-G_U*404 left/right cursor movement, if the cursor405 stays within the same line406-----------------------------------------------------------------------407 408Note: If the cursor keys take you out of Insert mode, check the 'noesckeys'409option.410 411The CTRL-O command sometimes has a side effect: If the cursor was beyond the412end of the line, it will be put on the last character in the line. In413mappings it's often better to use <Esc> (first put an "x" in the text, <Esc>414will then always put the cursor on it). Or use CTRL-\ CTRL-O, but then415beware of the cursor possibly being beyond the end of the line. Note that the416command following CTRL-\ CTRL-O can still move the cursor, it is not restored417to its original position.418 419The CTRL-O command takes you to Normal mode. If you then use a command enter420Insert mode again it normally doesn't nest. Thus when typing "a<C-O>a" and421then <Esc> takes you back to Normal mode, you do not need to type <Esc> twice.422An exception is when not typing the command, e.g. when executing a mapping or423sourcing a script. This makes mappings work that briefly switch to Insert424mode.425 426The shifted cursor keys are not available on all terminals.427 428Another side effect is that a count specified before the "i" or "a" command is429ignored. That is because repeating the effect of the command after CTRL-O is430too complicated.431 432An example for using CTRL-G u: >433 434 :inoremap <C-H> <C-G>u<C-H>435 436This redefines the backspace key to start a new undo sequence. You can now437undo the effect of the backspace key, without changing what you typed before438that, with CTRL-O u. Another example: >439 440 :inoremap <CR> <C-]><C-G>u<CR>441 442This starts a new undo block at each line break. It also expands443abbreviations before this.444 445An example for using CTRL-G U: >446 447 inoremap <Left> <C-G>U<Left>448 inoremap <Right> <C-G>U<Right>449 inoremap <expr> <Home> col('.') == match(getline('.'), '\S') + 1 ?450 \ repeat('<C-G>U<Left>', col('.') - 1) :451 \ (col('.') < match(getline('.'), '\S') ?452 \ repeat('<C-G>U<Right>', match(getline('.'), '\S') + 0) :453 \ repeat('<C-G>U<Left>', col('.') - 1 - match(getline('.'), '\S')))454 inoremap <expr> <End> repeat('<C-G>U<Right>', col('$') - col('.'))455 inoremap ( ()<C-G>U<Left>456 457This makes it possible to use the cursor keys in Insert mode, without starting458a new undo block and therefore using |.| (redo) will work as expected. Also459entering a text like (with the "(" mapping from above):460 461 Lorem ipsum (dolor462 463will be repeatable by using |.| to the expected464 465 Lorem ipsum (dolor)466 467Using CTRL-O splits undo: the text typed before and after it is undone468separately. If you want to avoid this (e.g., in a mapping) you might be able469to use CTRL-R = |i_CTRL-R|. E.g., to call a function: >470 :imap <F2> <C-R>=MyFunc()<CR>471 472When the 'whichwrap' option is set appropriately, the <Left> and <Right>473keys on the first/last character in the line make the cursor wrap to the474previous/next line.475 476The CTRL-G j and CTRL-G k commands can be used to insert text in front of a477column. Example: >478 int i;479 int j;480Position the cursor on the first "int", type "istatic <C-G>j ". The481result is: >482 static int i;483 int j;484When inserting the same text in front of the column in every line, use the485Visual blockwise command "I" |v_b_I|.486 487==============================================================================4883. 'textwidth' and 'wrapmargin' options *ins-textwidth*489 490The 'textwidth' option can be used to automatically break a line before it491gets too long. Set the 'textwidth' option to the desired maximum line492length. If you then type more characters (not spaces or tabs), the493last word will be put on a new line (unless it is the only word on the494line). If you set 'textwidth' to 0, this feature is disabled.495 496The 'wrapmargin' option does almost the same. The difference is that497'textwidth' has a fixed width while 'wrapmargin' depends on the width of the498screen. When using 'wrapmargin' this is equal to using 'textwidth' with a499value equal to (columns - 'wrapmargin'), where columns is the width of the500screen.501 502When 'textwidth' and 'wrapmargin' are both set, 'textwidth' is used.503 504If you don't really want to break the line, but view the line wrapped at a505convenient place, see the 'linebreak' option.506 507The line is only broken automatically when using Insert mode, or when508appending to a line. When in replace mode and the line length is not509changed, the line will not be broken.510 511Long lines are broken if you enter a non-white character after the margin.512The situations where a line will be broken can be restricted by adding513characters to the 'formatoptions' option:514"l" Only break a line if it was not longer than 'textwidth' when the insert515 started.516"v" Only break at a white character that has been entered during the517 current insert command. This is mostly Vi-compatible.518"lv" Only break if the line was not longer than 'textwidth' when the insert519 started and only at a white character that has been entered during the520 current insert command. Only differs from "l" when entering non-white521 characters while crossing the 'textwidth' boundary.522 523Normally an internal function will be used to decide where to break the line.524If you want to do it in a different way set the 'formatexpr' option to an525expression that will take care of the line break.526 527If you want to format a block of text, you can use the "gq" operator. Type528"gq" and a movement command to move the cursor to the end of the block. In529many cases, the command "gq}" will do what you want (format until the end of530paragraph). Alternatively, you can use "gqap", which will format the whole531paragraph, no matter where the cursor currently is. Or you can use Visual532mode: hit "v", move to the end of the block, and type "gq". See also |gq|.533 534==============================================================================5354. 'expandtab', 'softtabstop' and 'smarttab' options *ins-expandtab*536 537If the 'expandtab' option is on, spaces will be used to fill the amount of538whitespace of the tab. If you want to enter a real <Tab>, type CTRL-V first539(use CTRL-Q when CTRL-V is mapped |i_CTRL-Q|).540The 'expandtab' option is off by default. Note that in Replace mode, a single541character is replaced with several spaces. The result of this is that the542number of characters in the line increases. Backspacing will delete one543space at a time. The original character will be put back for only one space544that you backspace over (the last one).545 546 *ins-softtabstop*547When the 'softtabstop' option is non-zero, a <Tab> inserts 'softtabstop'548positions, and a <BS> used to delete white space, will delete 'softtabstop'549positions. This feels like 'tabstop' was set to 'softtabstop', but a real550<Tab> character still takes 'tabstop' positions, so your file will still look551correct when used by other applications.552 553If 'softtabstop' is non-zero, a <BS> will try to delete as much white space to554move to the previous 'softtabstop' position, except when the previously555inserted character is a space, then it will only delete the character before556the cursor. Otherwise you cannot always delete a single character before the557cursor. You will have to delete 'softtabstop' characters first, and then type558extra spaces to get where you want to be.559 560 *ins-smarttab*561When the 'smarttab' option is on, the <Tab> key indents by 'shiftwidth' if the562cursor is in leading whitespace. The <BS> key has the opposite effect. This563behaves as if 'softtabstop' were set to the value of 'shiftwidth'. This564option allows the user to set 'softtabstop' to a value other than 'shiftwidth'565and still use the <Tab> key for indentation.566 567==============================================================================5685. Replace mode *Replace* *Replace-mode* *mode-replace*569 570Enter Replace mode with the "R" command in normal mode.571 572In Replace mode, one character in the line is deleted for every character you573type. If there is no character to delete (at the end of the line), the574typed character is appended (as in Insert mode). Thus the number of575characters in a line stays the same until you get to the end of the line.576If a <NL> is typed, a line break is inserted and no character is deleted.577 578Be careful with <Tab> characters. If you type a normal printing character in579its place, the number of characters is still the same, but the number of580columns will become smaller.581 582If you delete characters in Replace mode (with <BS>, CTRL-W, or CTRL-U), what583happens is that you delete the changes. The characters that were replaced584are restored. If you had typed past the existing text, the characters you585added are deleted. This is effectively a character-at-a-time undo.586 587If the 'expandtab' option is on, a <Tab> will replace one character with588several spaces. The result of this is that the number of characters in the589line increases. Backspacing will delete one space at a time. The original590character will be put back for only one space that you backspace over (the591last one).592 593==============================================================================5946. Virtual Replace mode *vreplace-mode* *Virtual-Replace-mode*595 596Enter Virtual Replace mode with the "gR" command in normal mode.597{not available when compiled without the |+vreplace| feature}598 599Virtual Replace mode is similar to Replace mode, but instead of replacing600actual characters in the file, you are replacing screen real estate, so that601characters further on in the file never appear to move.602 603So if you type a <Tab> it may replace several normal characters, and if you604type a letter on top of a <Tab> it may not replace anything at all, since the605<Tab> will still line up to the same place as before.606 607Typing a <NL> still doesn't cause characters later in the file to appear to608move. The rest of the current line will be replaced by the <NL> (that is,609they are deleted), and replacing continues on the next line. A new line is610NOT inserted unless you go past the end of the file.611 612Interesting effects are seen when using CTRL-T and CTRL-D. The characters613before the cursor are shifted sideways as normal, but characters later in the614line still remain still. CTRL-T will hide some of the old line under the615shifted characters, but CTRL-D will reveal them again.616 617As with Replace mode, using <BS> etc will bring back the characters that were618replaced. This still works in conjunction with 'smartindent', CTRL-T and619CTRL-D, 'expandtab', 'smarttab', 'softtabstop', etc.620 621In 'list' mode, Virtual Replace mode acts as if it was not in 'list' mode,622unless "L" is in 'cpoptions'.623 624Note that the only situations for which characters beyond the cursor should625appear to move are in List mode 'list', and occasionally when 'wrap' is set626(and the line changes length to become shorter or wider than the width of the627screen). In other cases spaces may be inserted to avoid following characters628to move.629 630This mode is very useful for editing <Tab> separated columns in tables, for631entering new data while keeping all the columns aligned.632 633==============================================================================6347. Insert mode completion *ins-completion*635 636In Insert and Replace mode, there are several commands to complete part of a637keyword or line that has been typed. This is useful if you are using638complicated keywords (e.g., function names with capitals and underscores).639 640Completion can be done for:641 6421. Whole lines |i_CTRL-X_CTRL-L|6432. keywords in the current file |i_CTRL-X_CTRL-N|6443. keywords in 'dictionary' |i_CTRL-X_CTRL-K|6454. keywords in 'thesaurus', thesaurus-style |i_CTRL-X_CTRL-T|6465. keywords in the current and included files |i_CTRL-X_CTRL-I|6476. tags |i_CTRL-X_CTRL-]|6487. file names |i_CTRL-X_CTRL-F|6498. definitions or macros |i_CTRL-X_CTRL-D|6509. Vim command-line |i_CTRL-X_CTRL-V|65110. User defined completion |i_CTRL-X_CTRL-U|65211. omni completion |i_CTRL-X_CTRL-O|65312. Spelling suggestions |i_CTRL-X_s|65413. completions from 'complete' |i_CTRL-N| |i_CTRL-P|65514. contents from registers |i_CTRL-X_CTRL-R|656 657Additionally, |i_CTRL-X_CTRL-Z| stops completion without changing the text.658 659All these, except CTRL-N and CTRL-P, are done in CTRL-X mode. This is a660sub-mode of Insert and Replace modes. You enter CTRL-X mode by typing CTRL-X661and one of the CTRL-X commands. You exit CTRL-X mode by typing a key that is662not a valid CTRL-X mode command. Valid keys are the CTRL-X command itself,663CTRL-N (next), and CTRL-P (previous).664 665By default, the possible completions are showed in a menu and the first666completion is inserted into the text. This can be adjusted with667'completeopt'.668 669To get the current completion information, |complete_info()| can be used.670Also see the 'infercase' option if you want to adjust the case of the match.671 672When inserting a selected candidate word from the |popup-menu|, the part of673the candidate word that does not match the query is highlighted using674|hl-ComplMatchIns|. If fuzzy is enabled in 'completeopt', highlighting will675not be applied.676 677 *complete_CTRL-E*678When completion is active you can use CTRL-E to stop it and go back to the679originally typed text. The CTRL-E will not be inserted.680 681 *complete_CTRL-Y*682When the popup menu is displayed you can use CTRL-Y to stop completion and683accept the currently selected entry. The CTRL-Y is not inserted. Typing a684space, Enter, or some other unprintable character will leave completion mode685and insert that typed character.686 687When the popup menu is displayed there are a few more special keys, see688|popupmenu-keys|.689 690Note: The keys that are valid in CTRL-X mode are not mapped. This allows for691`:map <C-F> <C-X><C-F>` to work (assuming "<" is not in 'cpo'). The key that692ends CTRL-X mode (any key that is not a valid CTRL-X mode command) is mapped.693Also, when doing completion with 'complete' mappings apply as usual.694 695 *E565*696Note: While completion is active Insert mode can't be used recursively and697buffer text cannot be changed. Mappings that somehow invoke ":normal i.."698will generate an E565 error.699 700The following mappings are suggested to make typing the completion commands701a bit easier (although they will hide other commands; this requires "<" is not702in 'cpo'): >703 :inoremap <C-]> <C-X><C-]>704 :inoremap <C-F> <C-X><C-F>705 :inoremap <C-D> <C-X><C-D>706 :inoremap <C-L> <C-X><C-L>707 708As a special case, typing CTRL-R to perform register insertion (see709|i_CTRL-R|) will not exit CTRL-X mode. This is primarily to allow the use of710the '=' register to call some function to determine the next operation. If711the contents of the register (or result of the '=' register evaluation) are712not valid CTRL-X mode keys, then CTRL-X mode will be exited as if those keys713had been typed.714 715For example, the following will map <Tab> to either actually insert a <Tab> if716the current line is currently only whitespace, or start/continue a CTRL-N717completion operation: >718 719 function! CleverTab()720 if strpart( getline('.'), 0, col('.')-1 ) =~ '^\s*$'721 return "\<Tab>"722 else723 return "\<C-N>"724 endif725 endfunction726 inoremap <Tab> <C-R>=CleverTab()<CR>727 728 729 730Completing whole lines *compl-whole-line*731 732 *i_CTRL-X_CTRL-L*733CTRL-X CTRL-L Search backwards for a line that starts with the734 same characters as those in the current line before735 the cursor. Indent is ignored. The matching line is736 inserted in front of the cursor.737 The 'complete' option is used to decide which buffers738 are searched for a match. Both loaded and unloaded739 buffers are used.740 CTRL-L or741 CTRL-P Search backwards for next matching line. This line742 replaces the previous matching line.743 744 CTRL-N Search forward for next matching line. This line745 replaces the previous matching line.746 747 CTRL-X CTRL-L After expanding a line you can additionally get the748 line next to it by typing CTRL-X CTRL-L again, unless749 a double CTRL-X is used. Only works for loaded750 buffers.751 752Completing keywords in current file *compl-current*753 754 *i_CTRL-X_CTRL-P*755 *i_CTRL-X_CTRL-N*756CTRL-X CTRL-N Search forwards for words that start with the keyword757 in front of the cursor. The found keyword is inserted758 in front of the cursor.759 760CTRL-X CTRL-P Search backwards for words that start with the keyword761 in front of the cursor. The found keyword is inserted762 in front of the cursor.763 764 CTRL-N Search forward for next matching keyword. This765 keyword replaces the previous matching keyword.766 767 CTRL-P Search backwards for next matching keyword. This768 keyword replaces the previous matching keyword.769 770 CTRL-X CTRL-N or771 CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will772 copy the words following the previous expansion in773 other contexts unless a double CTRL-X is used.774 775If there is a keyword in front of the cursor (a name made out of alphabetic776characters and characters in 'iskeyword'), it is used as the search pattern,777with "\<" prepended (meaning: start of a word). Otherwise "\<\k\k" is used778as search pattern (start of any keyword of at least two characters).779 780In Replace mode, the number of characters that are replaced depends on the781length of the matched string. This works like typing the characters of the782matched string in Replace mode.783 784If there is not a valid keyword character before the cursor, any keyword of785at least two characters is matched.786 e.g., to get:787 printf("(%g, %g, %g)", vector[0], vector[1], vector[2]);788 just type:789 printf("(%g, %g, %g)", vector[0], ^P[1], ^P[2]);790 791The search wraps around the end of the file, the value of 'wrapscan' is not792used here.793 794Multiple repeats of the same completion are skipped; thus a different match795will be inserted at each CTRL-N and CTRL-P (unless there is only one796matching keyword).797 798Single character matches are never included, as they usually just get in799the way of what you were really after.800 e.g., to get:801 printf("name = %s\n", name);802 just type:803 printf("name = %s\n", n^P);804 or even:805 printf("name = %s\n", ^P);806The 'n' in '\n' is skipped.807 808After expanding a word, you can use CTRL-X CTRL-P or CTRL-X CTRL-N to get the809word following the expansion in other contexts. These sequences search for810the text just expanded and further expand by getting an extra word. This is811useful if you need to repeat a sequence of complicated words. Although CTRL-P812and CTRL-N look just for strings of at least two characters, CTRL-X CTRL-P and813CTRL-X CTRL-N can be used to expand words of just one character.814 e.g., to get:815 México816 you can type:817 M^N^P^X^P^X^P818CTRL-N starts the expansion and then CTRL-P takes back the single character819"M", the next two CTRL-X CTRL-P's get the words "é" and ";xico".820 821If the previous expansion was split, because it got longer than 'textwidth',822then just the text in the current line will be used.823 824If the match found is at the end of a line, then the first word in the next825line will be inserted and the message "Word from other line" displayed, if826this word is accepted the next CTRL-X CTRL-P or CTRL-X CTRL-N will search827for those lines starting with this word.828 829 830Completing keywords in 'dictionary' *compl-dictionary*831 832 *i_CTRL-X_CTRL-K*833CTRL-X CTRL-K Search the files given with the 'dictionary' option834 for words that start with the keyword in front of the835 cursor. This is like CTRL-N, but only the dictionary836 files are searched, not the current file. The found837 keyword is inserted in front of the cursor. This838 could potentially be pretty slow, since all matches839 are found before the first match is used. By default,840 the 'dictionary' option is empty.841 For suggestions where to find a list of words, see the842 'dictionary' option.843 'ignorecase', 'smartcase' and 'infercase' apply.844 845 CTRL-K or846 CTRL-N Search forward for next matching keyword. This847 keyword replaces the previous matching keyword.848 849 CTRL-P Search backwards for next matching keyword. This850 keyword replaces the previous matching keyword.851 852 853Completing words in 'thesaurus' *compl-thesaurus*854 855 *i_CTRL-X_CTRL-T*856CTRL-X CTRL-T Works as CTRL-X CTRL-K, but in a special way. It uses857 the 'thesaurus' option instead of 'dictionary'. If a858 match is found in the thesaurus file, all the859 remaining words on the same line are included as860 matches, even though they don't complete the word.861 Thus a word can be completely replaced.862 863 CTRL-T or864 CTRL-N Search forward for next matching keyword. This865 keyword replaces the previous matching keyword.866 867 CTRL-P Search backwards for next matching keyword. This868 keyword replaces the previous matching keyword.869 870In the file used by the 'thesaurus' option each line in the file should871contain words with similar meaning, separated by non-keyword characters (white872space is preferred). Maximum line length is 510 bytes.873 874For an example, imagine the 'thesaurus' file has a line like this: >875 angry furious mad enraged876Placing the cursor after the letters "ang" and typing CTRL-X CTRL-T would877complete the word "angry"; subsequent presses would change the word to878"furious", "mad" etc.879 880Other uses include translation between two languages, or grouping API881functions by keyword.882 883An English word list was added to this github issue:884https://github.com/vim/vim/issues/629#issuecomment-443293282885Unpack thesaurus_pkg.zip, put the thesaurus.txt file somewhere, e.g.886~/.vim/thesaurus/english.txt, and the 'thesaurus' option to this file name.887 888 889Completing keywords with 'thesaurusfunc' *compl-thesaurusfunc*890 891If the 'thesaurusfunc' option is set, then the user specified function is892invoked to get the list of completion matches and the 'thesaurus' option is893not used. See |complete-functions| for an explanation of how the function is894invoked and what it should return.895 896Here is an example that uses the "aiksaurus" command (provided by Magnus897Groß): >898 899 func Thesaur(findstart, base)900 if a:findstart901 return searchpos('\<', 'bnW', line('.'))[1] - 1902 endif903 let res = []904 let h = ''905 for l in systemlist('aiksaurus ' .. shellescape(a:base))906 if l[:3] == '=== '907 let h = '(' .. substitute(l[4:], ' =*$', ')', '')908 elseif l ==# 'Alphabetically similar known words are: '909 let h = "\U0001f52e"910 elseif l[0] =~ '\a' || (h ==# "\U0001f52e" && l[0] ==# "\t")911 call extend(res, map(split(substitute(l, '^\t', '', ''), ', '), {_, val -> {'word': val, 'menu': h}}))912 endif913 endfor914 return res915 endfunc916 917 if exists('+thesaurusfunc')918 set thesaurusfunc=Thesaur919 endif920 921 922Completing keywords in the current and included files *compl-keyword*923 924The 'include' option is used to specify a line that contains an include file925name. The 'path' option is used to search for include files.926 927 *i_CTRL-X_CTRL-I*928CTRL-X CTRL-I Search for the first keyword in the current and929 included files that starts with the same characters930 as those before the cursor. The matched keyword is931 inserted in front of the cursor.932 933 CTRL-N Search forwards for next matching keyword. This934 keyword replaces the previous matching keyword.935 Note: CTRL-I is the same as <Tab>, which is likely to936 be typed after a successful completion, therefore937 CTRL-I is not used for searching for the next match.938 939 CTRL-P Search backward for previous matching keyword. This940 keyword replaces the previous matching keyword.941 942 CTRL-X CTRL-I Further use of CTRL-X CTRL-I will copy the words943 following the previous expansion in other contexts944 unless a double CTRL-X is used.945 946Completing tags *compl-tag*947 *i_CTRL-X_CTRL-]*948CTRL-X CTRL-] Search for the first tag that starts with the same949 characters as before the cursor. The matching tag is950 inserted in front of the cursor. Alphabetic951 characters and characters in 'iskeyword' are used952 to decide which characters are included in the tag953 name (same as for a keyword). See also |CTRL-]|.954 The 'showfulltag' option can be used to add context955 from around the tag definition.956 CTRL-] or957 CTRL-N Search forwards for next matching tag. This tag958 replaces the previous matching tag.959 960 CTRL-P Search backward for previous matching tag. This tag961 replaces the previous matching tag.962 963 964Completing file names *compl-filename*965 *i_CTRL-X_CTRL-F*966CTRL-X CTRL-F Search for the first file name that starts with the967 same characters as before the cursor. The matching968 file name is inserted in front of the cursor.969 Alphabetic characters and characters in 'isfname'970 are used to decide which characters are included in971 the file name. Note: the 'path' option is not used972 here (yet).973 CTRL-F or974 CTRL-N Search forwards for next matching file name. This975 file name replaces the previous matching file name.976 977 CTRL-P Search backward for previous matching file name.978 This file name replaces the previous matching file979 name.980 981 982Completing definitions or macros *compl-define*983 984The 'define' option is used to specify a line that contains a definition.985The 'include' option is used to specify a line that contains an include file986name. The 'path' option is used to search for include files.987 988 *i_CTRL-X_CTRL-D*989CTRL-X CTRL-D Search in the current and included files for the990 first definition (or macro) name that starts with991 the same characters as before the cursor. The found992 definition name is inserted in front of the cursor.993 CTRL-D or994 CTRL-N Search forwards for next matching macro name. This995 macro name replaces the previous matching macro996 name.997 998 CTRL-P Search backward for previous matching macro name.999 This macro name replaces the previous matching macro1000 name.1001 1002 CTRL-X CTRL-D Further use of CTRL-X CTRL-D will copy the words1003 following the previous expansion in other contexts1004 unless a double CTRL-X is used.1005 1006 1007Completing Vim commands *compl-vim*1008 1009Completion is context-sensitive. It works like on the Command-line. It1010completes an Ex command as well as its arguments. This is useful when writing1011a Vim script.1012 1013 *i_CTRL-X_CTRL-V*1014CTRL-X CTRL-V Guess what kind of item is in front of the cursor and1015 find the first match for it.1016 Note: When CTRL-V is mapped you can often use CTRL-Q1017 instead of |i_CTRL-Q|.1018 CTRL-V or1019 CTRL-N Search forwards for next match. This match replaces1020 the previous one.1021 1022 CTRL-P Search backwards for previous match. This match1023 replaces the previous one.1024 1025 CTRL-X CTRL-V Further use of CTRL-X CTRL-V will do the same as1026 CTRL-V. This allows mapping a key to do Vim command1027 completion, for example: >1028 :imap <Tab> <C-X><C-V>1029 1030 1031Completing contents from registers *compl-register-words*1032 *i_CTRL-X_CTRL-R*1033CTRL-X CTRL-R Guess what kind of item is in front of the cursor from1034 all registers and find the first match for it.1035 Further use of CTRL-R (without CTRL-X) will insert the1036 register content, see |i_CTRL-R|.1037 'ignorecase' applies to the matching.1038 1039 CTRL-N Search forwards for next match. This match replaces1040 the previous one.1041 1042 CTRL-P Search backwards for previous match. This match1043 replaces the previous one.1044 1045 CTRL-X CTRL-R Further use of CTRL-X CTRL-R will copy the line1046 following the previous expansion in other contexts1047 unless a double CTRL-X is used (e.g. this switches1048 from completing register words to register contents).1049 1050User defined completion *compl-function*1051 1052Completion is done by a function that can be defined by the user with the1053'completefunc' option. See below for how the function is called and an1054example |complete-functions|.1055 1056 *i_CTRL-X_CTRL-U*1057CTRL-X CTRL-U Guess what kind of item is in front of the cursor and1058 find the first match for it.1059 CTRL-U or1060 CTRL-N Use the next match. This match replaces the previous1061 one.1062 1063 CTRL-P Use the previous match. This match replaces the1064 previous one.1065 1066 1067Omni completion *compl-omni*1068 1069Completion is done by a function that can be defined by the user with the1070'omnifunc' option. This is to be used for filetype-specific completion.1071 1072See below for how the function is called and an example |complete-functions|.1073For remarks about specific filetypes see |compl-omni-filetypes|.1074More completion scripts will appear, check www.vim.org. Currently there is a1075first version for C++.1076 1077 *i_CTRL-X_CTRL-O*1078CTRL-X CTRL-O Guess what kind of item is in front of the cursor and1079 find the first match for it.1080 CTRL-O or1081 CTRL-N Use the next match. This match replaces the previous1082 one.1083 1084 CTRL-P Use the previous match. This match replaces the1085 previous one.1086 1087 1088Spelling suggestions *compl-spelling*1089 1090A word before or at the cursor is located and correctly spelled words are1091suggested to replace it. If there is a badly spelled word in the line, before1092or under the cursor, the cursor is moved to after it. Otherwise the word just1093before the cursor is used for suggestions, even though it isn't badly spelled.1094 1095NOTE: CTRL-S suspends display in many Unix terminals. Use 's' instead. Type1096CTRL-Q to resume displaying.1097 1098 *i_CTRL-X_CTRL-S* *i_CTRL-X_s*1099CTRL-X CTRL-S or1100CTRL-X s Locate the word in front of the cursor and find the1101 first spell suggestion for it.1102 CTRL-S or1103 CTRL-N Use the next suggestion. This replaces the previous1104 one. Note that you can't use 's' here.1105 1106 CTRL-P Use the previous suggestion. This replaces the1107 previous one.1108 1109 1110Completing from different sources *compl-generic*1111 1112 *i_CTRL-N*1113CTRL-N Find the next match for a word ending at the cursor,1114 using the sources specified in the 'complete' option.1115 All sources complete from keywords, except functions,1116 which may complete from non-keyword. The matched1117 text is inserted before the cursor.1118 1119 *i_CTRL-P*1120CTRL-P Same as CTRL-N, but find the previous match.1121 1122 CTRL-N Search forward through the matches and insert the1123 next one.1124 1125 CTRL-P Search backward through the matches and insert the1126 previous one.1127 1128 CTRL-X CTRL-N or1129 CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will1130 copy the words following the previous expansion in1131 other contexts unless a double CTRL-X is used.1132 1133 1134Stop completion *compl-stop*1135 1136 *i_CTRL-X_CTRL-Z*1137CTRL-X CTRL-Z Stop completion without changing the text.1138 1139 1140AUTOCOMPLETION *ins-autocompletion*1141 1142Vim can display a completion menu as you type, similar to using |i_CTRL-N|,1143but triggered automatically. See 'autocomplete'. The menu items are1144collected from the sources listed in the 'complete' option, in order.1145 1146A decaying timeout keeps Vim responsive. Sources earlier in the 'complete'1147list get more time (higher priority), but all sources receive at least a small1148time slice.1149 1150This mode is fully compatible with other completion modes. You can invoke1151any of them at any time by typing |CTRL-X|, which temporarily suspends1152autocompletion. To use |i_CTRL-N| or |i_CTRL-X_CTRL-N| specifically, press1153|CTRL-E| first to dismiss the popup menu (see |complete_CTRL-E|).1154 1155 *ins-autocompletion-example*1156Example setup ~1157A typical configuration for automatic completion with a popup menu: >1158 set autocomplete1159 set complete=.^5,w^5,b^5,u^51160 set completeopt=popup1161 1162 inoremap <silent><expr> <Tab> pumvisible() ? "\<C-n>" : "\<Tab>"1163 inoremap <silent><expr> <S-Tab> pumvisible() ? "\<C-p>" : "\<S-Tab>"1164<1165This enables automatic completion with suggestions from the current buffer,1166other windows, and listed buffers, displayed in a popup menu. Each source is1167limited to 5 candidates. <Tab> and <S-Tab> move through the items when the1168menu is visible. Optionally, add "preinsert" to 'completeopt' to insert the1169longest common prefix automatically. Additional sources (e.g., LSP clients)1170may be added to 'complete' to improve completion as required.1171 1172See also 'autocomplete', 'autocompletedelay' and 'autocompletetimeout'.1173 1174For command-line autocompletion, see |cmdline-autocompletion|.1175 1176 1177FUNCTIONS FOR FINDING COMPLETIONS *complete-functions*1178 1179This applies to 'completefunc', 'thesaurusfunc' and 'omnifunc'.1180 1181The function is called in two different ways:1182- First the function is called to find the start of the text to be completed.1183- Later the function is called to actually find the matches.1184 1185On the first invocation the arguments are:1186 a:findstart 11187 a:base empty1188 1189The function must return the column where the completion starts. It must be a1190number between zero and the cursor column "col('.')". This involves looking1191at the characters just before the cursor and including those characters that1192could be part of the completed item. The text between this column and the1193cursor column will be replaced with the matches. If the returned value is1194larger than the cursor column, the cursor column is used.1195 1196Negative return values:1197 -2 To cancel silently and stay in completion mode.1198 -3 To cancel silently and leave completion mode.1199 Another negative value: completion starts at the cursor column1200