Insert

Nvim:help pages,generated fromsource using thetree-sitter-vimdoc parser.

Insert-modeInserting and replacing textmode-ins-repl

Most of this file is about Insert and Replace mode. At the end are a fewcommands for inserting text in other ways.

An overview of the most often used commands can be found in chapter 24 of theuser manualusr_24.txt.

Also see'virtualedit', for moving the cursor to positions where there is nocharacter. Useful for editing a table.

1. Special keysins-special-keys

In Insert and Replace mode, the following characters have a special meaning;other characters are inserted directly. To insert one of these specialcharacters into the buffer, precede it withCTRL-V. To insert a<Nul>character use "CTRL-VCTRL-@" or "CTRL-V 000". On some systems, you have touse "CTRL-V 003" to insert aCTRL-C. Note: WhenCTRL-V is mapped you canoften useCTRL-Q insteadi_CTRL-Q.

If you are working in a special language mode when inserting text, see the'langmap' option,'langmap', on how to avoid switching this mode on and offall the time.

charaction

<Esc> orCTRL-[End insert or Replace mode, go back to Normal mode. Finishabbreviation.Note: If your<Esc> key is hard to hit, tryCTRL-[ instead.i_METAi_ALTALT (META) may act like<Esc> if the chord is not mapped.For example<A-x> acts like<Esc>x if<A-x> does not have aninsert-mode mapping.i_CTRL-C
CTRL-CQuit insert mode, go back to Normal mode. Do not check forabbreviations. Does not trigger theInsertLeave autocommandevent.

i_CTRL-@
CTRL-@Insert previously inserted text and stop insert.

i_CTRL-A
CTRL-AInsert previously inserted text.

i_CTRL-Hi_<BS>i_BS<BS> orCTRL-HDelete the character before the cursor (seei_backspacingabout joining lines).i_<Del>i_DEL<Del>Delete the character under the cursor. If the cursor is atthe end of the line, and the'backspace' option includes"eol" (the default), delete the<EOL>; the next line isappended after the current one.i_CTRL-W
CTRL-WDelete the word before the cursor (seei_backspacing aboutjoining lines). See the section "word motions",word-motions, for the definition of a word.i_CTRL-W-default
By default, sets a new undo point before deleting.default-mappingsi_CTRL-U
CTRL-UDelete all characters that were entered after starting Insertmode and before the cursor in the current line.If there are no newly entered characters and'backspace' isnot empty, delete all characters before the cursor in thecurrent line.If C-indenting is enabled the indent will be adjusted if theline becomes blank.Seei_backspacing about joining lines.i_CTRL-U-default
By default, sets a new undo point before deleting.default-mappingsi_CTRL-Ii_<Tab>i_Tab<Tab> orCTRL-I Insert a tab. If the'expandtab' option is on, theequivalent number of spaces is inserted (useCTRL-V<Tab> toavoid the expansion; useCTRL-Q<Tab> ifCTRL-V is mappedi_CTRL-Q). See also the'smarttab' option andins-expandtab.i_CTRL-Ji_<NL><NL> orCTRL-JBegin new line.i_CTRL-Mi_<CR><CR> orCTRL-MBegin new line.i_CTRL-K
CTRL-K{char1} [char2]Enter digraph (seedigraphs). When{char1} is a specialkey, the code for that key is inserted in <> form. Forexample, the string "<S-Space>" can be entered by typing<C-K><S-Space> (two keys). Neither char is considered formapping.

CTRL-NFind next keyword (seei_CTRL-N).CTRL-PFind previous keyword (seei_CTRL-P).

CTRL-R{register}i_CTRL-R
Insert the contents of a register. Between typingCTRL-R andthe second character, '"' will be displayed to indicate thatyou are expected to enter the name of a register. When usedwith named or clipboard registers (A-Z,a-z,0-9,+) text isinserted literally like pasting with "p". For other registers,the text is inserted as if you typed it, but mappings andabbreviations are not used. If you have options like'textwidth','formatoptions', or'autoindent' set, this willinfluence what will be inserted. This is different from whathappens with the "p" command and pasting with the mouse.Special registers:'"'the unnamed register, containing the text ofthe last delete or yank'%'the current file name'#'the alternate file name"*"the clipboard contents (X11: primary selection)'+'the clipboard contents'/'the last search pattern':'the last command-line'.'the last inserted texti_CTRL-R_-
'-'the last small (less than a line) deleteregister. This is repeatable using. sinceit remembers the register to put instead ofthe literal text to insert.i_CTRL-R_=
'='the expression register: you are prompted toenter an expression (seeexpression)Note that 0x80 (128 decimal) is used forspecial keys. E.g., you can use this to movethe cursor up:CTRL-R ="\<Up>"you can use this to insert a register astyped withCTRL-R =@reg.UseCTRL-RCTRL-R to insert text literally.When the result is aList the items are usedas lines. They can have line breaks insidetoo.When the result is a Float it's automaticallyconverted to a String.When append() or setline() is invoked the undosequence will be broken.Seeregisters about registers.

CTRL-RCTRL-R{register}i_CTRL-R_CTRL-R
Insert the contents of a register. Works like using a singleCTRL-R, but the text is inserted literally, not as if typed.This differs when the register contains characters like<BS>.Example, where register a contains "ab^Hc":

CTRL-R aresults in "ac".CTRL-R CTRL-R aresults in "ab^Hc".

Options'textwidth','formatoptions', etc. still apply. Ifyou also want to avoid these, useCTRL-RCTRL-O, see below.The '.' register (last inserted text) is still inserted astyped.After this command, the '.' register contains the text fromthe register as if it was inserted by typing it.

CTRL-RCTRL-O{register}i_CTRL-R_CTRL-O
Insert the contents of a register literally and don'tauto-indent. Does the same as pasting with the mouse<MiddleMouse>. When the register is linewise this willinsert the text above the current line, like withP.The '.' register (last inserted text) is still inserted astyped.After this command, the '.' register contains the commandtyped and not the text. I.e., the literals "^R^O" and not thetext from the register.Does not replace characters inReplace-mode!

CTRL-RCTRL-P{register}i_CTRL-R_CTRL-P
Insert the contents of a register literally and fix theindent, like[<MiddleMouse>.The '.' register (last inserted text) is still inserted astyped.After this command, the '.' register contains the commandtyped and not the text. I.e., the literals "^R^P" and not thetext from the register.Does not replace characters inReplace-mode!

i_CTRL-T
CTRL-TInsert one shiftwidth of indent at the start of the currentline. The indent is always rounded to a'shiftwidth'.i_CTRL-D
CTRL-DDelete one shiftwidth of indent at the start of the currentline. The indent is always rounded to a'shiftwidth'.

i_0_CTRL-D
0CTRL-DDelete all indent in the current line.

i_^_CTRL-D
^CTRL-DDelete all indent in the current line. The indent isrestored in the next line. This is useful when inserting alabel.

i_CTRL-V
CTRL-VInsert next non-digit literally. It's also possible to enterthe decimal, octal or hexadecimal value of a characteri_CTRL-V_digit.The characters typed right afterCTRL-V are not considered formapping.For special keys, the CTRL modifier may be included into thekey to produce a control character. If there is no controlcharacter for the key then itskey-notation is inserted.Note: WhenCTRL-V is mapped (e.g., to paste text) you canoften useCTRL-Q insteadi_CTRL-Q.

i_CTRL-Q
CTRL-QSame asCTRL-V.Note: Some terminal connections may eatCTRL-Q, it doesn'twork then. It does work in the GUI.

CTRL-SHIFT-Vi_CTRL-SHIFT-Vi_CTRL-SHIFT-Q

CTRL-SHIFT-QWorks just likeCTRL-V, but do not try to include the CTRLmodifier into the key.Note: WhenCTRL-SHIFT-V is intercepted by your system (e.g.,to paste text) you can often useCTRL-SHIFT-Q instead.However, in some terminals (e.g. GNOME Terminal),CTRL-SHIFT-Qquits the terminal without confirmation.

CTRL-XEnterCTRL-X mode. This is a sub-mode where commands canbe given to complete words or scroll the window. Seei_CTRL-X andins-completion.

i_CTRL-E
CTRL-EInsert the character which is below the cursor.i_CTRL-Y
CTRL-YInsert the character which is above the cursor.Note that forCTRL-E andCTRL-Y'textwidth' is not used, to beable to copy characters from a long line.

i_CTRL-_
CTRL-_Switch between insert direction, by toggling'revins'.

CTRL-_ moves the cursor to the end of the typed text.

This command is only available when the'allowrevins' optionis set.Please refer torileft.txt for more information aboutright-to-left mode.

i_CTRL-^
CTRL-^Toggle the use of typing language characters.When language:lmap mappings are defined:

If'iminsert' is 1 (langmap mappings used) it becomes 0 (no langmap mappings used).

If'iminsert' has another value it becomes 1, thus langmap mappings are enabled.When no language mappings are defined:

If'iminsert' is 2 (Input Method used) it becomes 0 (no Input Method used).

If'iminsert' has another value it becomes 2, thus the Input Method is enabled.When set to 1, the value of the "b:keymap_name" variable, the'keymap' option or "<lang>" appears in the status line.The language mappings are normally used to type charactersthat are different from what the keyboard produces. The'keymap' option can be used to install a whole number of them.

i_CTRL-]
CTRL-]Trigger abbreviation, without inserting a character.

i_<Insert>
<Insert>Toggle between Insert and Replace mode.

The effect of the<BS>,CTRL-W, andCTRL-U depend on the'backspace' option(unless'revins' is set). This is a comma-separated list of items:

item action

indent allow backspacing over autoindenteol allow backspacing over line breaks (join lines)start allow backspacing over the start of insert;CTRL-W andCTRL-U stop once at the start of insert.nostop like start, exceptCTRL-W andCTRL-U do not stop at the start of insert.

When'backspace' is empty, Vi compatible backspacing is used. You cannotbackspace over autoindent, before column 1 or before where insert started.

If the'backspace' option does contain "eol" and the cursor is in column 1when one of the three keys is used, the current line is joined with theprevious line. This effectively deletes the<EOL> in front of the cursor.

i_CTRL-V_digit
WithCTRL-V the decimal, octal or hexadecimal value of a character can beentered directly. This way you can enter any character, except a line break(<NL>, value 10). There are five ways to enter the character value:

first charmode max nr of chars max value

(none)decimal 3255o or Ooctal 3377 (255)x or Xhexadecimal 2ff (255)uhexadecimal 4ffff (65535)Uhexadecimal 87fffffff (2147483647)

Normally you would type the maximum number of characters. Thus to enter aspace (value 32) you would type<C-V>032. You can omit the leading zero, inwhich case the character typed after the number must be a non-digit. Thishappens for the other modes as well: As soon as you type a character that isinvalid for the mode, the value before it will be used and the "invalid"character is dealt with in the normal way.

If you enter a value of 10, it will end up in the file as a 0. The 10 is a<NL>, which is used internally to represent the<Nul> character. When writingthe buffer to a file, the<NL> character is translated into<Nul>. The<NL>character is written at the end of each line. Thus if you want to insert a<NL> character in a file you will have to make a line break.Also see'fileformat'.

i_CTRL-Xinsert_expandCTRL-X enters a sub-mode where several commands can be used. Most of thesecommands do keyword completion; seeins-completion.

Two commands can be used to scroll the window up or down, without exitinginsert mode:

i_CTRL-X_CTRL-E
CTRL-XCTRL-Escroll window one line up.When doing completion look here:complete_CTRL-E

i_CTRL-X_CTRL-Y
CTRL-XCTRL-Yscroll window one line down.When doing completion look here:complete_CTRL-Y

AfterCTRL-X is pressed, eachCTRL-E (CTRL-Y) scrolls the window up (down) byone line unless that would cause the cursor to move from its current positionin the file. As soon as another key is pressed,CTRL-X mode is exited andthat key is interpreted as in Insert mode.

2. Special special keysins-special-special

The following keys are special. They stop the current insert, do something,and then restart insertion. This means you can do something without gettingout of Insert mode. This is very handy if you prefer to use the Insert modeall the time, just like editors that don't have a separate Normal mode. Youcan useCTRL-O if you want to map a function key to a command.

The changes (inserted or deleted characters) before and after these keys canbe undone separately. Only the last change can be redone and always behaveslike an "i" command.

charaction

`<Up>`cursor one line upi_<Up>

<Down>cursor one line downi_<Down>
CTRL-G<Up>cursor one line up, insert start columni_CTRL-G_<Up>
CTRL-G kcursor one line up, insert start columni_CTRL-G_k
CTRL-GCTRL-Kcursor one line up, insert start columni_CTRL-G_CTRL-K
CTRL-G<Down>cursor one line down, insert start columni_CTRL-G_<Down>CTRL-G jcursor one line down, insert start columni_CTRL-G_jCTRL-GCTRL-Jcursor one line down, insert start columni_CTRL-G_CTRL-J<Left>cursor one character lefti_<Left>
<Right>cursor one character righti_<Right>
<S-Left>cursor one word back (like "b" command)i_<S-Left>
<C-Left>cursor one word back (like "b" command)i_<C-Left>
<S-Right>cursor one word forward (like "w" command)i_<S-Right><C-Right>cursor one word forward (like "w" command)i_<C-Right><Home>cursor to first char in the linei_<Home>
<End>cursor to after last char in the linei_<End>
<C-Home>cursor to first char in the filei_<C-Home>
<C-End>cursor to after last char in the filei_<C-End>
<LeftMouse>cursor to position of mouse clicki_<LeftMouse>
<S-Up>move window one page upi_<S-Up>
<PageUp>move window one page upi_<PageUp>
<S-Down>move window one page downi_<S-Down>
<PageDown>move window one page downi_<PageDown>
<ScrollWheelDown> move window three lines downi_<ScrollWheelDown><S-ScrollWheelDown> move window one page downi_<S-ScrollWheelDown>
<ScrollWheelUp> move window three lines upi_<ScrollWheelUp>
<S-ScrollWheelUp> move window one page upi_<S-ScrollWheelUp>
<ScrollWheelLeft> move window six columns lefti_<ScrollWheelLeft><S-ScrollWheelLeft> move window one page lefti_<S-ScrollWheelLeft>
<ScrollWheelRight> move window six columns righti_<ScrollWheelRight><S-ScrollWheelRight> move window one page righti_<S-ScrollWheelRight>
CTRL-Oexecute one command, return to Insert modei_CTRL-OCTRL-\CTRL-OlikeCTRL-O but don't move the cursori_CTRL-\_CTRL-O
CTRL-G uclose undo sequence, start new changei_CTRL-G_u
CTRL-G Udon't start a new undo block with the nexti_CTRL-G_Uleft/right cursor movement, if the cursorstays within the same line

TheCTRL-O command sometimes has a side effect: If the cursor was beyond theend of the line, it will be put on the last character in the line. Inmappings it's often better to use<Esc> (first put an "x" in the text,<Esc>will then always put the cursor on it). Or useCTRL-\CTRL-O, but thenbeware of the cursor possibly being beyond the end of the line. Note that thecommand followingCTRL-\CTRL-O can still move the cursor, it is not restoredto its original position.

TheCTRL-O command takes you to Normal mode. If you then use a command enterInsert mode again it normally doesn't nest. Thus when typing "a<C-O>a" andthen<Esc> takes you back to Normal mode, you do not need to type<Esc> twice.An exception is when not typing the command, e.g. when executing a mapping orsourcing a script. This makes mappings work that briefly switch to Insertmode.

The shifted cursor keys are not available on all terminals.

Another side effect is that a count specified before the "i" or "a" command isignored. That is because repeating the effect of the command afterCTRL-O istoo complicated.

An example for usingCTRL-G u:

:inoremap <C-H> <C-G>u<C-H>

This redefines the backspace key to start a new undo sequence. You can nowundo the effect of the backspace key, without changing what you typed beforethat, withCTRL-O u. Another example:

:inoremap <CR> <C-]><C-G>u<CR>

This starts a new undo block at each line break. It also expandsabbreviations before this.

An example for usingCTRL-G U:

inoremap <Left>  <C-G>U<Left>inoremap <Right> <C-G>U<Right>inoremap <expr> <Home> col('.') == match(getline('.'), '\S') + 1 ? \ repeat('<C-G>U<Left>', col('.') - 1) : \ (col('.') < match(getline('.'), '\S') ? \     repeat('<C-G>U<Right>', match(getline('.'), '\S') + 0) : \     repeat('<C-G>U<Left>', col('.') - 1 - match(getline('.'), '\S')))inoremap <expr> <End> repeat('<C-G>U<Right>', col('$') - col('.'))inoremap ( ()<C-G>U<Left>

This makes it possible to use the cursor keys in Insert mode, without startinga new undo block and therefore using. (redo) will work as expected. Alsoentering a text like (with the "(" mapping from above):

Lorem ipsum (dolor

will be repeatable by using. to the expected

Lorem ipsum (dolor)

UsingCTRL-O splits undo: the text typed before and after it is undoneseparately. If you want to avoid this (e.g., in a mapping) you might be ableto useCTRL-R =i_CTRL-R. E.g., to call a function:

:imap <F2> <C-R>=MyFunc()<CR>

When the'whichwrap' option is set appropriately, the<Left> and<Right>keys on the first/last character in the line make the cursor wrap to theprevious/next line.

TheCTRL-G j andCTRL-G k commands can be used to insert text in front of acolumn. Example:

int i;int j;

Position the cursor on the first "int", type "istatic<C-G>j ". Theresult is:

static int i;       int j;

When inserting the same text in front of the column in every line, use theVisual blockwise command "I"v_b_I.

3.'textwidth' and'wrapmargin' optionsins-textwidth

The'textwidth' option can be used to automatically break a line before itgets too long. Set the'textwidth' option to the desired maximum linelength. If you then type more characters (not spaces or tabs), thelast word will be put on a new line (unless it is the only word on theline). If you set'textwidth' to 0, this feature is disabled.

The'wrapmargin' option does almost the same. The difference is that'textwidth' has a fixed width while'wrapmargin' depends on the width of thescreen. When using'wrapmargin' this is equal to using'textwidth' with avalue equal to (columns -'wrapmargin'), where columns is the width of thescreen.

When'textwidth' and'wrapmargin' are both set,'textwidth' is used.

If you don't really want to break the line, but view the line wrapped at aconvenient place, see the'linebreak' option.

The line is only broken automatically when using Insert mode, or whenappending to a line. When in replace mode and the line length is notchanged, the line will not be broken.

Long lines are broken if you enter a non-white character after the margin.The situations where a line will be broken can be restricted by addingcharacters to the'formatoptions' option:"l" Only break a line if it was not longer than'textwidth' when the insert started."v" Only break at a white character that has been entered during the current insert command. This is mostly Vi-compatible."lv" Only break if the line was not longer than'textwidth' when the insert started and only at a white character that has been entered during the current insert command. Only differs from "l" when entering non-white characters while crossing the'textwidth' boundary.

Normally an internal function will be used to decide where to break the line.If you want to do it in a different way set the'formatexpr' option to anexpression that will take care of the line break.

If you want to format a block of text, you can use the "gq" operator. Type"gq" and a movement command to move the cursor to the end of the block. Inmany cases, the command "gq}" will do what you want (format until the end ofparagraph). Alternatively, you can use "gqap", which will format the wholeparagraph, no matter where the cursor currently is. Or you can use Visualmode: hit "v", move to the end of the block, and type "gq". See alsogq.

4.'expandtab','softtabstop' and'smarttab' optionsins-expandtab

If the'expandtab' option is on, spaces will be used to fill the amount ofwhitespace of the tab. If you want to enter a real<Tab>, typeCTRL-V first(useCTRL-Q whenCTRL-V is mappedi_CTRL-Q).The'expandtab' option is off by default. Note that in Replace mode, a singlecharacter is replaced with several spaces. The result of this is that thenumber of characters in the line increases. Backspacing will delete onespace at a time. The original character will be put back for only one spacethat you backspace over (the last one).

ins-softtabstop
When the'softtabstop' option is non-zero, a<Tab> inserts'softtabstop'positions, and a<BS> used to delete white space, will delete'softtabstop'positions. This feels like'tabstop' was set to'softtabstop', but a real<Tab> character still takes'tabstop' positions, so your file will still lookcorrect when used by other applications.

If'softtabstop' is non-zero, a<BS> will try to delete as much white space tomove to the previous'softtabstop' position, except when the previouslyinserted character is a space, then it will only delete the character beforethe cursor. Otherwise you cannot always delete a single character before thecursor. You will have to delete'softtabstop' characters first, and then typeextra spaces to get where you want to be.

ins-smarttab
When the'smarttab' option is on, the<Tab> key indents by'shiftwidth' if thecursor is in leading whitespace. The<BS> key has the opposite effect. Thisbehaves as if'softtabstop' were set to the value of'shiftwidth'. Thisoption allows the user to set'softtabstop' to a value other than'shiftwidth'and still use the<Tab> key for indentation.

5. Replace modeReplaceReplace-modemode-replace

Enter Replace mode with the "R" command in normal mode.

In Replace mode, one character in the line is deleted for every character youtype. If there is no character to delete (at the end of the line), thetyped character is appended (as in Insert mode). Thus the number ofcharacters in a line stays the same until you get to the end of the line.If a<NL> is typed, a line break is inserted and no character is deleted.

Be careful with<Tab> characters. If you type a normal printing character inits place, the number of characters is still the same, but the number ofcolumns will become smaller.

If you delete characters in Replace mode (with<BS>,CTRL-W, orCTRL-U), whathappens is that you delete the changes. The characters that were replacedare restored. If you had typed past the existing text, the characters youadded are deleted. This is effectively a character-at-a-time undo.

If the'expandtab' option is on, a<Tab> will replace one character withseveral spaces. The result of this is that the number of characters in theline increases. Backspacing will delete one space at a time. The originalcharacter will be put back for only one space that you backspace over (thelast one).

6. Virtual Replace modevreplace-modeVirtual-Replace-mode

Enter Virtual Replace mode with the "gR" command in normal mode.

Virtual Replace mode is similar to Replace mode, but instead of replacingactual characters in the file, you are replacing screen real estate, so thatcharacters further on in the file never appear to move.

So if you type a<Tab> it may replace several normal characters, and if youtype a letter on top of a<Tab> it may not replace anything at all, since the<Tab> will still line up to the same place as before.

Typing a<NL> still doesn't cause characters later in the file to appear tomove. The rest of the current line will be replaced by the<NL> (that is,they are deleted), and replacing continues on the next line. A new line isNOT inserted unless you go past the end of the file.

Interesting effects are seen when usingCTRL-T andCTRL-D. The charactersbefore the cursor are shifted sideways as normal, but characters later in theline still remain still.CTRL-T will hide some of the old line under theshifted characters, butCTRL-D will reveal them again.

As with Replace mode, using<BS> etc will bring back the characters that werereplaced. This still works in conjunction with'smartindent',CTRL-T andCTRL-D,'expandtab','smarttab','softtabstop', etc.

In'list' mode, Virtual Replace mode acts as if it was not in'list' mode,unless "L" is in'cpoptions'.

Note that the only situations for which characters beyond the cursor shouldappear to move are in List mode'list', and occasionally when'wrap' is set(and the line changes length to become shorter or wider than the width of thescreen). In other cases spaces may be inserted to avoid following charactersto move.

This mode is very useful for editing<Tab> separated columns in tables, forentering new data while keeping all the columns aligned.

7. Insert mode completionins-completion

In Insert and Replace mode, there are several commands to complete part of akeyword or line that has been typed. This is useful if you are usingcomplicated keywords (e.g., function names with capitals and underscores).

Completion can be done for:

1. Whole linesi_CTRL-X_CTRL-L 2. keywords in the current filei_CTRL-X_CTRL-N 3. keywords in'dictionary'i_CTRL-X_CTRL-K 4. keywords in'thesaurus', thesaurus-stylei_CTRL-X_CTRL-T 5. keywords in the current and included filesi_CTRL-X_CTRL-I 6. tagsi_CTRL-X_CTRL-] 7. file namesi_CTRL-X_CTRL-F 8. definitions or macrosi_CTRL-X_CTRL-D 9. Vim command-linei_CTRL-X_CTRL-V 10. User defined completioni_CTRL-X_CTRL-U 11. omni completioni_CTRL-X_CTRL-O 12. Spelling suggestionsi_CTRL-X_s 13. completions from'complete'i_CTRL-N i_CTRL-P14. contents from registersi_CTRL-X_CTRL-R

Additionally,i_CTRL-X_CTRL-Z stops completion without changing the text.

All these, exceptCTRL-N andCTRL-P, are done inCTRL-X mode. This is asub-mode of Insert and Replace modes. You enterCTRL-X mode by typingCTRL-Xand one of theCTRL-X commands. You exitCTRL-X mode by typing a key that isnot a validCTRL-X mode command. Valid keys are theCTRL-X command itself,CTRL-N (next), andCTRL-P (previous).

By default, the possible completions are showed in a menu and the firstcompletion is inserted into the text. This can be adjusted with'completeopt'.

To get the current completion information,complete_info() can be used.Also see the'infercase' option if you want to adjust the case of the match.

When inserting a selected candidate word from thepopup-menu, the part ofthe candidate word that does not match the query is highlighted usinghl-ComplMatchIns. If fuzzy is enabled in'completeopt', highlighting willnot be applied.

complete_CTRL-E
When completion is active you can useCTRL-E to stop it and go back to theoriginally typed text. TheCTRL-E will not be inserted.

complete_CTRL-Y
When the popup menu is displayed,CTRL-Y stops completion and accepts thecurrently selected entry. Typing a space, Enter, or some other unprintablecharacter will leave completion mode and insert that typed character. If youwant to use<Enter> to accept a completion item, use this mapping:

inoremap <expr> <cr> pumvisible() ? '<c-y>' : '<cr>'

When the popup menu is displayed there are a few more special keys, seepopupmenu-keys.

Note: The keys that are valid inCTRL-X mode are not mapped. This allows for:map <C-F> <C-X><C-F> to work. The key that endsCTRL-X mode (any key thatis not a validCTRL-X mode command) is mapped. Also, when doing completionwith'complete' mappings apply as usual.

E565
Note: While completion is active Insert mode can't be used recursively andbuffer text cannot be changed. Mappings that somehow invoke ":normal i.."will generate an E565 error.

The following mappings are suggested to make typing the completion commandsa bit easier (although they will hide other commands):

:inoremap <C-]> <C-X><C-]>:inoremap <C-F> <C-X><C-F>:inoremap <C-D> <C-X><C-D>:inoremap <C-L> <C-X><C-L>

As a special case, typingCTRL-R to perform register insertion (seei_CTRL-R) will not exitCTRL-X mode. This is primarily to allow the use ofthe '=' register to call some function to determine the next operation. Ifthe contents of the register (or result of the '=' register evaluation) arenot validCTRL-X mode keys, thenCTRL-X mode will be exited as if those keyshad been typed.

For example, the following will map<Tab> to either actually insert a<Tab> ifthe current line is currently only whitespace, or start/continue aCTRL-Ncompletion operation:

function! CleverTab()   if strpart( getline('.'), 0, col('.')-1 ) =~ '^\s*$'      return "\<Tab>"   else      return "\<C-N>"   endifendfunctioninoremap <Tab> <C-R>=CleverTab()<CR>

Completing whole linescompl-whole-line

i_CTRL-X_CTRL-L
CTRL-XCTRL-LSearch backwards for a line that starts with thesame characters as those in the current line beforethe cursor. Indent is ignored. The matching line isinserted in front of the cursor.The'complete' option is used to decide which buffersare searched for a match. Both loaded and unloadedbuffers are used.CTRL-LorCTRL-PSearch backwards for next matching line. This linereplaces the previous matching line.

CTRL-NSearch forward for next matching line. This linereplaces the previous matching line.

CTRL-XCTRL-LAfter expanding a line you can additionally get theline next to it by typingCTRL-XCTRL-L again, unlessa doubleCTRL-X is used. Only works for loadedbuffers.

Completing keywords in current filecompl-current

i_CTRL-X_CTRL-P
i_CTRL-X_CTRL-N
CTRL-XCTRL-NSearch forwards for words that start with the keywordin front of the cursor. The found keyword is insertedin front of the cursor.

CTRL-XCTRL-PSearch backwards for words that start with the keywordin front of the cursor. The found keyword is insertedin front of the cursor.

CTRL-NSearch forward for next matching keyword. Thiskeyword replaces the previous matching keyword.

CTRL-PSearch backwards for next matching keyword. Thiskeyword replaces the previous matching keyword.

CTRL-XCTRL-N orCTRL-XCTRL-PFurther use ofCTRL-XCTRL-N orCTRL-XCTRL-P willcopy the words following the previous expansion inother contexts unless a doubleCTRL-X is used.

If there is a keyword in front of the cursor (a name made out of alphabeticcharacters and characters in'iskeyword'), it is used as the search pattern,with "\<" prepended (meaning: start of a word). Otherwise "\<\k\k" is usedas search pattern (start of any keyword of at least two characters).

In Replace mode, the number of characters that are replaced depends on thelength of the matched string. This works like typing the characters of thematched string in Replace mode.

If there is not a valid keyword character before the cursor, any keyword ofat least two characters is matched.e.g., to get: printf("(%g, %g, %g)", vector[0], vector[1], vector[2]);just type: printf("(%g, %g, %g)", vector[0], ^P[1], ^P[2]);

The search wraps around the end of the file, the value of'wrapscan' is notused here.

Multiple repeats of the same completion are skipped; thus a different matchwill be inserted at eachCTRL-N andCTRL-P (unless there is only onematching keyword).

Single character matches are never included, as they usually just get inthe way of what you were really after.e.g., to get:printf("name = %s\n", name);just type:printf("name = %s\n", n^P);or even:printf("name = %s\n", ^P);The 'n' in '\n' is skipped.

After expanding a word, you can useCTRL-XCTRL-P orCTRL-XCTRL-N to get theword following the expansion in other contexts. These sequences search forthe text just expanded and further expand by getting an extra word. This isuseful if you need to repeat a sequence of complicated words. AlthoughCTRL-PandCTRL-N look just for strings of at least two characters,CTRL-XCTRL-P andCTRL-XCTRL-N can be used to expand words of just one character.e.g., to get:Méxicoyou can type:M^N^P^X^P^X^PCTRL-N starts the expansion and thenCTRL-P takes back the single character"M", the next twoCTRL-XCTRL-P's get the words "&eacute" and ";xico".

If the previous expansion was split, because it got longer than'textwidth',then just the text in the current line will be used.

If the match found is at the end of a line, then the first word in the nextline will be inserted and the message "Word from other line" displayed, ifthis word is accepted the nextCTRL-XCTRL-P orCTRL-XCTRL-N will searchfor those lines starting with this word.

Completing keywords in'dictionary'compl-dictionary

i_CTRL-X_CTRL-K
CTRL-XCTRL-KSearch the files given with the'dictionary' optionfor words that start with the keyword in front of thecursor. This is likeCTRL-N, but only the dictionaryfiles are searched, not the current file. The foundkeyword is inserted in front of the cursor. Thiscould potentially be pretty slow, since all matchesare found before the first match is used. By default,the'dictionary' option is empty.For suggestions where to find a list of words, see the'dictionary' option.'ignorecase','smartcase' and'infercase' apply.

CTRL-KorCTRL-NSearch forward for next matching keyword. Thiskeyword replaces the previous matching keyword.

CTRL-PSearch backwards for next matching keyword. Thiskeyword replaces the previous matching keyword.

Completing words in'thesaurus'compl-thesaurus

i_CTRL-X_CTRL-T
CTRL-XCTRL-TWorks asCTRL-XCTRL-K, but in a special way. It usesthe'thesaurus' option instead of'dictionary'. If amatch is found in the thesaurus file, all theremaining words on the same line are included asmatches, even though they don't complete the word.Thus a word can be completely replaced.

CTRL-TorCTRL-NSearch forward for next matching keyword. Thiskeyword replaces the previous matching keyword.

CTRL-PSearch backwards for next matching keyword. Thiskeyword replaces the previous matching keyword.

In the file used by the'thesaurus' option each line in the file shouldcontain words with similar meaning, separated by non-keyword characters (whitespace is preferred). Maximum line length is 510 bytes.

For an example, imagine the'thesaurus' file has a line like this:

angry furious mad enraged

Placing the cursor after the letters "ang" and typingCTRL-XCTRL-T wouldcomplete the word "angry"; subsequent presses would change the word to"furious", "mad" etc.

Other uses include translation between two languages, or grouping APIfunctions by keyword.

An English word list was added to this github issue:https://github.com/vim/vim/issues/629#issuecomment-443293282Unpack thesaurus_pkg.zip, put the thesaurus.txt file somewhere, e.g.~/.vim/thesaurus/english.txt, and the'thesaurus' option to this file name.

Completing keywords with'thesaurusfunc'compl-thesaurusfunc

If the'thesaurusfunc' option is set, then the user specified function isinvoked to get the list of completion matches and the'thesaurus' option isnot used. Seecomplete-functions for an explanation of how the function isinvoked and what it should return.

Here is an example that uses the "aiksaurus" command (provided by MagnusGroß):

func Thesaur(findstart, base)  if a:findstart    return searchpos('\<', 'bnW', line('.'))[1] - 1  endif  let res = []  let h = ''  for l in systemlist('aiksaurus ' .. shellescape(a:base))    if l[:3] == '=== '      let h = '(' .. substitute(l[4:], ' =*$', ')', '')    elseif l ==# 'Alphabetically similar known words are: '      let h = "\U0001f52e"    elseif l[0] =~ '\a' || (h ==# "\U0001f52e" && l[0] ==# "\t")      call extend(res, map(split(substitute(l, '^\t', '', ''), ', '), {_, val -> {'word': val, 'menu': h}}))    endif  endfor  return resendfuncif exists('+thesaurusfunc')  set thesaurusfunc=Thesaurendif

Completing keywords in the current and included filescompl-keyword

The'include' option is used to specify a line that contains an include filename. The'path' option is used to search for include files.

i_CTRL-X_CTRL-I
CTRL-XCTRL-ISearch for the first keyword in the current andincluded files that starts with the same charactersas those before the cursor. The matched keyword isinserted in front of the cursor.

CTRL-NSearch forwards for next matching keyword. Thiskeyword replaces the previous matching keyword.Note:CTRL-I is the same as<Tab>, which is likely tobe typed after a successful completion, thereforeCTRL-I is not used for searching for the next match.

CTRL-PSearch backward for previous matching keyword. Thiskeyword replaces the previous matching keyword.

CTRL-XCTRL-IFurther use ofCTRL-XCTRL-I will copy the wordsfollowing the previous expansion in other contextsunless a doubleCTRL-X is used.

Completing tagscompl-tag
i_CTRL-X_CTRL-]
CTRL-XCTRL-]Search for the first tag that starts with the samecharacters as before the cursor. The matching tag isinserted in front of the cursor. Alphabeticcharacters and characters in'iskeyword' are usedto decide which characters are included in the tagname (same as for a keyword). See alsoCTRL-].The'showfulltag' option can be used to add contextfrom around the tag definition.CTRL-]orCTRL-NSearch forwards for next matching tag. This tagreplaces the previous matching tag.

CTRL-PSearch backward for previous matching tag. This tagreplaces the previous matching tag.

Completing file namescompl-filename
i_CTRL-X_CTRL-F
CTRL-XCTRL-FSearch for the first file name that starts with thesame characters as before the cursor. The matchingfile name is inserted in front of the cursor.Alphabetic characters and characters in'isfname'are used to decide which characters are included inthe file name. Note: the'path' option is not usedhere (yet).CTRL-ForCTRL-NSearch forwards for next matching file name. Thisfile name replaces the previous matching file name.

CTRL-PSearch backward for previous matching file name.This file name replaces the previous matching filename.

Completing definitions or macroscompl-define

The'define' option is used to specify a line that contains a definition.The'include' option is used to specify a line that contains an include filename. The'path' option is used to search for include files.

i_CTRL-X_CTRL-D
CTRL-XCTRL-DSearch in the current and included files for thefirst definition (or macro) name that starts withthe same characters as before the cursor. The founddefinition name is inserted in front of the cursor.CTRL-DorCTRL-NSearch forwards for next matching macro name. Thismacro name replaces the previous matching macroname.

CTRL-PSearch backward for previous matching macro name.This macro name replaces the previous matching macroname.

CTRL-XCTRL-DFurther use ofCTRL-XCTRL-D will copy the wordsfollowing the previous expansion in other contextsunless a doubleCTRL-X is used.

Completing Vim commandscompl-vim

Completion is context-sensitive. It works like on the Command-line. Itcompletes an Ex command as well as its arguments. This is useful when writinga Vim script.

i_CTRL-X_CTRL-V
CTRL-XCTRL-VGuess what kind of item is in front of the cursor andfind the first match for it.Note: WhenCTRL-V is mapped you can often useCTRL-Qinstead ofi_CTRL-Q.CTRL-VorCTRL-NSearch forwards for next match. This match replacesthe previous one.

CTRL-PSearch backwards for previous match. This matchreplaces the previous one.

CTRL-XCTRL-VFurther use ofCTRL-XCTRL-V will do the same asCTRL-V. This allows mapping a key to do Vim commandcompletion, for example:

:imap <Tab> <C-X><C-V>

Completing contents from registerscompl-register-words
i_CTRL-X_CTRL-R
CTRL-XCTRL-RGuess what kind of item is in front of the cursor fromall registers and find the first match for it.Further use ofCTRL-R (withoutCTRL-X) will insert theregister content, seei_CTRL-R.'ignorecase' applies to the matching.

CTRL-NSearch forwards for next match. This match replacesthe previous one.

CTRL-PSearch backwards for previous match. This matchreplaces the previous one.

CTRL-XCTRL-RFurther use ofCTRL-XCTRL-R will copy the linefollowing the previous expansion in other contextsunless a doubleCTRL-X is used (e.g. this switchesfrom completing register words to register contents).

User defined completioncompl-function

Completion is done by a function that can be defined by the user with the'completefunc' option. See below for how the function is called and anexamplecomplete-functions.

i_CTRL-X_CTRL-U
CTRL-XCTRL-UGuess what kind of item is in front of the cursor andfind the first match for it.CTRL-UorCTRL-NUse the next match. This match replaces the previousone.

CTRL-PUse the previous match. This match replaces theprevious one.

Omni completionomnicompletioncompl-omni

Completion is done by a function that can be defined by the user with the'omnifunc' option. This is to be used for filetype-specific completion.

See below for how the function is called and an examplecomplete-functions.For remarks about specific filetypes seecompl-omni-filetypes.More completion scripts will appear, check www.vim.org. Currently there is afirst version for C++.

i_CTRL-X_CTRL-O
CTRL-XCTRL-OGuess what kind of item is in front of the cursor andfind the first match for it.CTRL-OorCTRL-NUse the next match. This match replaces the previousone.

CTRL-PUse the previous match. This match replaces theprevious one.

Spelling suggestionscompl-spelling

A word before or at the cursor is located and correctly spelled words aresuggested to replace it. If there is a badly spelled word in the line, beforeor under the cursor, the cursor is moved to after it. Otherwise the word justbefore the cursor is used for suggestions, even though it isn't badly spelled.

NOTE:CTRL-S suspends display in many Unix terminals. Use 's' instead. TypeCTRL-Q to resume displaying.

i_CTRL-X_CTRL-Si_CTRL-X_sCTRL-XCTRL-S orCTRL-X sLocate the word in front of the cursor and find thefirst spell suggestion for it.CTRL-SorCTRL-NUse the next suggestion. This replaces the previousone. Note that you can't use 's' here.

CTRL-PUse the previous suggestion. This replaces theprevious one.

Completing from different sourcescompl-generic

i_CTRL-N
CTRL-NFind the next match for a word ending at the cursor,using the sources specified in the'complete' option.All sources complete from keywords, except functions,which may complete from non-keyword. The matchedtext is inserted before the cursor.

i_CTRL-P
CTRL-PSame asCTRL-N, but find the previous match.

CTRL-NSearch forward through the matches and insert thenext one.

CTRL-PSearch backward through the matches and insert theprevious one.

CTRL-XCTRL-N orCTRL-XCTRL-PFurther use ofCTRL-XCTRL-N orCTRL-XCTRL-P willcopy the words following the previous expansion inother contexts unless a doubleCTRL-X is used.

Stop completioncompl-stop

i_CTRL-X_CTRL-Z
CTRL-XCTRL-ZStop completion without changing the text.

AUTOCOMPLETIONins-autocompletion

Vim can display a completion menu as you type, similar to usingi_CTRL-N,but triggered automatically. See'autocomplete'. The menu items arecollected from the sources listed in the'complete' option, in order.

A decaying timeout keeps Vim responsive. Sources earlier in the'complete'list get more time (higher priority), but all sources receive at least a smalltime slice.

This mode is fully compatible with other completion modes. You can invokeany of them at any time by typingCTRL-X, which temporarily suspendsautocompletion. To usei_CTRL-N ori_CTRL-X_CTRL-N specifically, pressCTRL-E first to dismiss the popup menu (seecomplete_CTRL-E).

ins-autocompletion-example

Example setup

A typical configuration for automatic completion with a popup menu:

set autocompleteset complete=.^5,w^5,b^5,u^5set completeopt=popupinoremap <silent><expr> <Tab>   pumvisible() ? "\<C-n>" : "\<Tab>"inoremap <silent><expr> <S-Tab> pumvisible() ? "\<C-p>" : "\<S-Tab>"

This enables automatic completion with suggestions from the current buffer,other windows, and listed buffers, displayed in a popup menu. Each source islimited to 5 candidates.<Tab> and<S-Tab> move through the items when themenu is visible. Optionally, add "preinsert" to'completeopt' to insert thelongest common prefix automatically. You can also add other completionsources to'complete' as needed.

For command-line autocompletion, seecmdline-autocompletion.

To get LSP-driven auto-completion, seelsp-completion.

FUNCTIONS FOR FINDING COMPLETIONScomplete-functions

This applies to'completefunc','thesaurusfunc' and'omnifunc'.

The function is called in two different ways:

First the function is called to find the start of the text to be completed.

Later the function is called to actually find the matches.

On the first invocation the arguments are: a:findstart 1 a:baseempty

The function must return the column where the completion starts. It must be anumber between zero and the cursor column "col('.')". This involves lookingat the characters just before the cursor and including those characters thatcould be part of the completed item. The text between this column and thecursor column will be replaced with the matches. If the returned value islarger than the cursor column, the cursor column is used.

Negative return values: -2To cancel silently and stay in completion mode. -3To cancel silently and leave completion mode. Another negative value: completion starts at the cursor column

On the second invocation the arguments are: a:findstart 0 a:basethe text with which matches should match; the text that waslocated in the first call (can be empty)

The function must return a List with the matching words. These matchesusually include the "a:base" text. When there are no matches return an emptyList. Note that the cursor may have moved since the first invocation, thetext may have been changed.

In order to return more information than the matching words, return a Dictthat contains the List. The Dict can have these items:wordsThe List of matching words (mandatory).refreshA string to control re-invocation of the function(optional).The only value currently recognized is "always", theeffect is that the function is called whenever theleading text is changed.Other items are ignored.

For acting upon end of completion, see theCompleteDonePre andCompleteDone autocommand event.

For example, the function can contain this:

let matches = ... list of words ...return {'words': matches, 'refresh': 'always'}

If looking for matches is time-consuming,complete_check() may be used tomaintain responsiveness.

complete-items
Each list item can either be a string or a Dictionary. When it is a string itis used as the completion. When it is a Dictionary it can contain theseitems:wordthe text that will be inserted, mandatoryabbrabbreviation of "word"; when not empty it is used inthe menu instead of "word"menuextra text for the popup menu, displayed after "word"or "abbr"infomore information about the item, can be displayed in apreview windowkindsingle letter indicating the type of completionicasewhen non-zero case is to be ignored when comparingitems to be equal; when omitted zero is used, thusitems that only differ in case are addedequalwhen non-zero, always treat this item to be equal whencomparing. Which means, "equal=1" disables filteringof this item.dupwhen non-zero this match will be added even when anitem with the same word is already present.emptywhen non-zero this match will be added even when it isan empty stringuser_datacustom data which is associated with the item andavailable inv:completed_item; it can be any type;defaults to an empty stringabbr_hlgroupan additional highlight group whose attributes arecombined withhl-PmenuSel andhl-Pmenu orhl-PmenuMatchSel andhl-PmenuMatch highlightattributes in the popup menu to apply cterm and guiproperties (with higher priority) like strikethroughto the completion items abbreviationkind_hlgroupan additional highlight group specifically for settingthe highlight attributes of the completion kind. Whenthis field is present, it will override thehl-PmenuKind highlight group, allowing for thecustomization of ctermfg and guifg properties for thecompletion kindmatchSee "matches" incomplete_info().

All of these except "icase", "equal", "dup" and "empty" must be a string. Ifan item does not meet these requirements then an error message is given andfurther items in the list are not used. You can mix string and Dictionaryitems in the returned list.

The "menu" item is used in the popup menu and may be truncated, thus it shouldbe relatively short. The "info" item can be longer, it will be displayed inthe preview window when "preview" appears in'completeopt'. The "info" itemwill also remain displayed after the popup menu has been removed. This isuseful for function arguments. Use a single space for "info" to removeexisting text in the preview window. The size of the preview window is threelines, but'previewheight' is used when it has a value of 1 or 2.

The "kind" item uses a single letter to indicate the kind of completion. Thismay be used to show the completion differently (different color or icon).Currently these types can be used:vvariableffunction or methodmmember of a struct or classttypedefd#define or macro

When searching for matches takes some time callcomplete_add() to add eachmatch to the total list. These matches should then not appear in the returnedlist! Callcomplete_check() now and then to allow the user to press a keywhile still searching for matches. Stop searching when it returns non-zero.

E840
The function is allowed to move the cursor, it is restored afterwards.The function is not allowed to move to another window or delete text.

An example that completes the names of the months:

fun! CompleteMonths(findstart, base)  if a:findstart    " locate the start of the word    let line = getline('.')    let start = col('.') - 1    while start > 0 && line[start - 1] =~ '\a'      let start -= 1    endwhile    return start  else    " find months matching with "a:base"    let res = []    for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")      if m =~ '^' .. a:base        call add(res, m)      endif    endfor    return res  endifendfunset completefunc=CompleteMonths

The same, but now pretending searching for matches is slow:

fun! CompleteMonths(findstart, base)  if a:findstart    " locate the start of the word    let line = getline('.')    let start = col('.') - 1    while start > 0 && line[start - 1] =~ '\a'      let start -= 1    endwhile    return start  else    " find months matching with "a:base"    for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")      if m =~ '^' .. a:base        call complete_add(m)      endif      sleep 300m" simulate searching for next match      if complete_check()        break      endif    endfor    return []  endifendfunset completefunc=CompleteMonths

INSERT COMPLETION POPUP MENUins-completion-menu

popupmenu-completion
Vim can display the matches in a simplistic popup menu.

The menu is used when:

The'completeopt' option contains "menu" or "menuone".

The terminal supports at least 8 colors.

There are at least two matches. One if "menuone" is used.

The'pumheight' option can be used to set a maximum height. The default is touse all space available.The'pumwidth' option can be used to set a minimum width. The default is 15characters.

compl-states
There are three states:1. A complete match has been inserted, e.g., after usingCTRL-N orCTRL-P.2. A cursor key has been used to select another match. The match was not inserted then, only the entry in the popup menu is highlighted.3. Only part of a match has been inserted and characters were typed or the backspace key was used. The list of matches was then adjusted for what is in front of the cursor.

You normally start in the first state, with the first match being inserted.When "longest" is in'completeopt' and there is more than one match you startin the third state.

If you select another match, e.g., withCTRL-N orCTRL-P, you go to the firststate. This doesn't change the list of matches.

When you are back at the original text then you are in the third state. Toget there right away you can use a mapping that usesCTRL-P right afterstarting the completion:

:imap <F7> <C-N><C-P>

popupmenu-keys
In the first state these keys have a special meaning:<BS> andCTRL-H Delete one character, find the matches for the word before the cursor. This reduces the list of matches, often to one entry, and switches to the second state. When'autocomplete' is active, clears the selected item in the menu.Any non-special character: Stop completion without changing the match and insert the typed character.

In the second and third state these keys have a special meaning:<BS> andCTRL-H Delete one character, find the matches for the shorter word before the cursor. This may find more matches. When'autocomplete' is active, clears the selected item in the menu.CTRL-L Add one character from the current match, may reduce the number of matches.any printable, non-white character: Add this character and reduce the number of matches.

In all three states these can be used:CTRL-Y Yes: Accept the currently selected match and stop completion.CTRL-E End completion, go back to what was there before selecting a match (what was typed or longest common string).<PageUp> Select a match several entries back, but don't insert it.<PageDown> Select a match several entries further, but don't insert it.<Up> Select the previous match, as ifCTRL-P was used, but don't insert it.<Down> Select the next match, as ifCTRL-N was used, but don't insert it.<Space> or<Tab> Stop completion without changing the match and insert the typed character.

The behavior of the<Enter> key depends on the state you are in:first state: Use the text as it is and insert a line break.second state: Insert the currently selected match.third state: Use the text as it is and insert a line break.

In other words: If you used the cursor keys to select another entry in thelist of matches then the<Enter> key inserts that match. If you typedsomething else then<Enter> inserts a line break.

The colors of the menu can be changed with these highlight groups:Pmenunormal itemhl-PmenuPmenuSelselected itemhl-PmenuSelPmenuSbarscrollbarhl-PmenuSbarPmenuThumbthumb of the scrollbarhl-PmenuThumb

There are no special mappings for when the popup menu is visible. However,you can use an Insert mode mapping that checks thepumvisible() function todo something different. Example:

:inoremap <Down> <C-R>=pumvisible() ? "\<lt>C-N>" : "\<lt>Down>"<CR>

You can use of<expr> in mapping to have the popup menu used when typing acharacter and some condition is met. For example, for typing a dot:

inoremap <expr> . MayComplete()func MayComplete()    if (can complete)      return ".\<C-X>\<C-O>"    endif    return '.'endfunc

See:map-<expr> for more info.

FILETYPE-SPECIFIC REMARKS FOR OMNI COMPLETIONcompl-omni-filetypes

The file used for{filetype} should be autoload/{filetype}complete.vimin'runtimepath'. Thus for "java" it is autoload/javacomplete.vim.

Cft-c-omni

Completion of C code requires a tags file. You should use Universal/Exuberant ctags, because it adds extra information that is needed forcompletion. You can find it here:Universal Ctags:https://ctags.io

Universal Ctags is preferred, Exuberant Ctags is no longer maintained.

If you want to complete system functions you can do something like this. Usectags to generate a tags file for all the system header files:

% ctags -R -f ~/.config/nvim/systags /usr/include /usr/local/include

In your vimrc file add this tags file to the'tags' option:

set tags+=~/.config/nvim/systags

When usingCTRL-XCTRL-O after a name without any "." or "->" it is completedfrom the tags file directly. This works for any identifier, also functionnames. If you want to complete a local variable name, which does not appearin the tags file, useCTRL-P instead.

When usingCTRL-XCTRL-O after something that has "." or "->" Vim will attemptto recognize the type of the variable and figure out what members it has.This means only members valid for the variable will be listed.

When a member name already was complete,CTRL-XCTRL-O will add a "." or"->" for composite types.

Vim doesn't include a C compiler, only the most obviously formatteddeclarations are recognized. Preprocessor stuff may cause confusion.When the same structure name appears in multiple places all possible membersare included.

CSSft-css-omni

Complete properties and their appropriate values according to CSS 2.1specification.

HTMLft-html-omni

XHTMLft-xhtml-omni

CTRL-XCTRL-O provides completion of various elements of (X)HTML files. It isdesigned to support writing of XHTML 1.0 Strict files but will also work forother versions of HTML. Features:

after "<" complete tag name depending on context (no div suggestion inside of an a tag); '/>' indicates empty tags

inside of tag complete proper attributes (no width attribute for an a tag); show also type of attribute; "*" indicates required attributes

when attribute has limited number of possible values help to complete them

complete names of entities

complete values of "class" and "id" attributes with data obtained from<style> tag and included CSS files

when completing value of "style" attribute or working inside of "style" tag switch toft-css-omni completion

when completing values of events attributes or working inside of "script" tag switch toft-javascript-omni completion

when used after "</"CTRL-XCTRL-O will close the last opened tag

Note: When used first time completion menu will be shown with little delay

this is time needed for loading of data file.Note: Completion may fail in badly formatted documents. In such case try torun:make command to detect formatting problems.

HTML flavorhtml-flavor

The default HTML completion depends on the filetype. For HTML files it isHTML 4.01 Transitional ('filetype' is "html"), for XHTML it is XHTML 1.0Strict ('filetype' is "xhtml").

When doing completion outside of any other tag you will have possibility tochoose DOCTYPE and the appropriate data file will be loaded and used for allnext completions.

More about format of data file inxml-omni-datafile. Some of the data filesmay be found on the Vim website (www).

Note that b:html_omni_flavor may point to a file with any XML data. Thismakes possible to mix PHP (ft-php-omni) completion with any XML dialect(assuming you have data file for it). Without setting that variable XHTML 1.0Strict will be used.

JAVASCRIPTft-javascript-omni

Completion of most elements of JavaScript language and DOM elements.

Complete:

variables

function name; show function arguments

function arguments

properties of variables trying to detect type of variable

complete DOM objects and properties depending on context

keywords of language

Completion works in separate JavaScript files (&ft==javascript), inside of<script> tag of (X)HTML and in values of event attributes (including scanningof external files).

DOM compatibility

At the moment (beginning of 2006) there are two main browsers - MS InternetExplorer and Mozilla Firefox. These two applications are covering over 90% ofmarket. Theoretically standards are created by W3C organisation(https://www.w3.org/) but they are not always followed/implemented.

IEFFW3C  Omni completion ~+/-+/-+    +     ~++-    +     ~+--    -     ~-+-    -     ~

Regardless from state of implementation in browsers but if element is definedin standards, completion plugin will place element in suggestion list. Whenboth major engines implemented element, even if this is not in standards itwill be suggested. All other elements are not placed in suggestion list.

LUAft-lua-omni

Luaftplugin sets'omnifunc' tovim.lua_omnifunc().

PHPft-php-omni

Completion of PHP code requires a tags file for completion of data fromexternal files and for class aware completion. You should use Universal/Exuberant ctags version 5.5.4 or newer. You can find it here:

Universal Ctags:https://ctags.io

Script completes:

after $ variables name

if variable was declared as object add "->", if tags file is available show name of class

after "->" complete only function and variable names specific for given class. To find class location and contents tags file is required. Because PHP isn't strongly typed language user can use @var tag to declare class:

/* @var $myVar myClass */$myVar->

Still, to find myClass contents tags file is required.

function names with additional info:

in case of built-in functions list of possible arguments and after | type data returned by function

in case of user function arguments and name of file where function was defined (if it is not current file)

constants names

class names after "new" declaration

Note: when doing completion first time Vim will load all necessary data intomemory. It may take several seconds. After next use of completion delayshould not be noticeable.

Script detects if cursor is inside <?php ?> tags. If it is outside it willautomatically switch to HTML/CSS/JavaScript completion. Note: contrary tooriginal HTML files completion of tags (and only tags) isn't context aware.

RUBYft-ruby-omni

NOTE:compl-omni for Ruby code requiresprovider-ruby to be installed.

Ruby completion will parse your buffer on demand in order to provide a list ofcompletions. These completions will be drawn from modules loaded by "require"and modules defined in the current buffer.

The completions provided byCTRL-XCTRL-O are sensitive to the context:

CONTEXT COMPLETIONS PROVIDED

1. Not inside a class definition Classes, constants and globals

2. Inside a class definition Methods or constants defined in the class

3. After '.', '::' or ':' Methods applicable to the object being dereferenced

4. After ':' or ':foo' Symbol name (beginning with "foo")

Notes:

Vim will load/evaluate code in order to provide completions. This may cause some code execution, which may be a concern. This is no longer enabled by default, to enable this feature add

let g:rubycomplete_buffer_loading = 1

<- In context 1 above, Vim can parse the entire buffer to add a list of classes to the completion results. This feature is turned off by default, to enable it add

let g:rubycomplete_classes_in_global = 1

to your vimrc

In context 2 above, anonymous classes are not supported.

In context 3 above, Vim will attempt to determine the methods supported by the object.

Vim can detect and load the Rails environment for files within a rails project. The feature is disabled by default, to enable it add

let g:rubycomplete_rails = 1

to your vimrc

SYNTAXft-syntax-omni

Vim has the ability to color syntax highlight nearly 500 languages. Part ofthis highlighting includes knowing what keywords are part of a language. Manyfiletypes already have custom completion scripts written for them, thesyntaxcomplete plugin provides basic completion for all other filetypes. Itdoes this by populating the omni completion list with the text Vim alreadyknows how to color highlight. It can be used for any filetype and provides aminimal language-sensitive completion.

To enable syntax code completion you can run:

setlocal omnifunc=syntaxcomplete#Complete

You can automate this by placing the following in yourinit.vim (after any":filetype" command):

if has("autocmd") && exists("+omnifunc")    autocmd Filetype *                \if &omnifunc == "" |                \setlocal omnifunc=syntaxcomplete#Complete |                \endifendif

The above will set completion to this script only if a specific plugin doesnot already exist for that filetype.

Each filetype can have a wide range of syntax items. The plugin allows you tocustomize which syntax groups to include or exclude from the list. Let's havea look at the PHP filetype to see how this works.

If you edit a file called, index.php, run the following command:

syntax list

The first thing you will notice is that there are many different syntaxgroups. The PHP language can include elements from different languages likeHTML, JavaScript and many more. The syntax plugin will only include syntaxgroups that begin with the filetype, "php", in this case. For example thesesyntax groups are included by default with the PHP: phpEnvVar, phpIntVar,phpFunctions.

If you wish non-filetype syntax items to also be included, you can use aregular expression syntax (added in version 13.0 ofautoload/syntaxcomplete.vim) to add items. Looking at the output from":syntax list" while editing a PHP file I can see some of these entries:

htmlArg,htmlTag,htmlTagName,javaScriptStatement,javaScriptGlobalObjects

To pick up any JavaScript and HTML keyword syntax groups while editing a PHPfile, you can use 3 different regexs, one for each language. Or you cansimply restrict the include groups to a particular value, without usinga regex string:

let g:omni_syntax_group_include_php = 'php\w\+,javaScript\w\+,html\w\+'let g:omni_syntax_group_include_php = 'phpFunctions,phpMethods'

The basic form of this variable is:

let g:omni_syntax_group_include_{filetype} = 'regex,comma,separated'

The PHP language has an enormous number of items which it knows how to syntaxhighlight. These items will be available within the omni completion list.

Some people may find this list unwieldy or are only interested in certainitems. There are two ways to prune this list (if necessary). If you findcertain syntax groups you do not wish displayed you can use two differentmethods to identify these groups. The first specifically lists the syntaxgroups by name. The second uses a regular expression to identify bothsyntax groups. Simply add one the following to your vimrc:

let g:omni_syntax_group_exclude_php = 'phpCoreConstant,phpConstant'let g:omni_syntax_group_exclude_php = 'php\w*Constant'

Add as many syntax groups to this list by comma separating them. The basicform of this variable is:

let g:omni_syntax_group_exclude_{filetype} = 'regex,comma,separated'

You can create as many of these variables as you need, varying only thefiletype at the end of the variable name.

The plugin uses the isKeyword option to determine where word boundaries arefor the syntax items. For example, in the Scheme language completion shouldinclude the "-", call-with-output-file. Depending on your filetype, this maynot provide the words you are expecting. Setting theg:omni_syntax_use_iskeyword option to 0 will force the syntax plugin to breakon word characters. This can be controlled adding the following to yourvimrc:

let g:omni_syntax_use_iskeyword = 0

For plugin developers, the plugin exposes a public function OmniSyntaxList.This function can be used to request a List of syntax items. When editing aSQL file (:e syntax.sql) you can use the ":syntax list" command to see thevarious groups and syntax items. For example:

syntax list

Yields data similar to this:

sqlOperator xxx some prior all like and any escape exists in is not

or intersect minus between distinct

links to Operator

sqlType xxx varbit varchar nvarchar bigint int uniqueidentifier

date money long tinyint unsigned xml text smalldate

double datetime nchar smallint numeric time bit char

varbinary binary smallmoney

image float integer timestamp real decimal

There are two syntax groups listed here: sqlOperator and sqlType. To retrievea List of syntax items you can call OmniSyntaxList a number of differentways. To retrieve all syntax items regardless of syntax group:

echo OmniSyntaxList( [] )

To retrieve only the syntax items for the sqlOperator syntax group:

echo OmniSyntaxList( ['sqlOperator'] )

To retrieve all syntax items for both the sqlOperator and sqlType groups:

echo OmniSyntaxList( ['sqlOperator', 'sqlType'] )

A regular expression can also be used:

echo OmniSyntaxList( ['sql\w\+'] )

From within a plugin, you would typically assign the output to a List:

let myKeywords = []let myKeywords = OmniSyntaxList( ['sqlKeyword'] )

SQLft-sql-omni

Completion for the SQL language includes statements, functions, keywords.It will also dynamically complete tables, procedures, views and column listswith data pulled directly from within a database. For detailed instructionsand a tutorial seeomni-sql-completion.

The SQL completion plugin can be used in conjunction with other completionplugins. For example, the PHP filetype has its own completion plugin.Since PHP is often used to generate dynamic website by accessing a database,the SQL completion plugin can also be enabled. This allows you to completePHP code and SQL code at the same time.

XMLft-xml-omni

Vim 7 provides a mechanism for context aware completion of XML files. Itdepends on a specialxml-omni-datafile and two commands::XMLns and:XMLent. Features are:

after "<" complete the tag name, depending on context

inside of a tag complete proper attributes

when an attribute has a limited number of possible values help to complete them

complete names of entities (defined inxml-omni-datafile and in the current file with "<!ENTITY" declarations)

when used after "</"CTRL-XCTRL-O will close the last opened tag

Format of XML data filexml-omni-datafile

XML data files are stored in the "autoload/xml" directory in'runtimepath'.Vim distribution provides examples of data files in the"$VIMRUNTIME/autoload/xml" directory. They have a meaningful name which willbe used in commands. It should be a unique name which will not createconflicts. For example, the name xhtml10s.vim means it is the data file forXHTML 1.0 Strict.

Each file contains a variable with a name like g:xmldata_xhtml10s . It isa compound from two parts:

1. "g:xmldata_" general prefix, constant for all data files2. "xhtml10s" the name of the file and the name of the described XML dialect; it will be used as an argument for the:XMLns command

Part two must be exactly the same as name of file.

The variable is aDictionary. Keys are tag names and each value is a twoelementList. The first element of the List is also a List with the namesof possible children. The second element is aDictionary with the names ofattributes as keys and the possible values of attributes as values. Example:

let g:xmldata_crippled = {\ "vimxmlentities": ["amp", "lt", "gt", "apos", "quot"],\ 'vimxmlroot': ['tag1'],\ 'tag1':\ [ ['childoftag1a', 'childoftag1b'], {'attroftag1a': [],\ 'attroftag1b': ['valueofattr1', 'valueofattr2']}],\ 'childoftag1a':\ [ [], {'attrofchild': ['attrofchild']}],\ 'childoftag1b':\ [ ['childoftag1a'], {'attrofchild': []}],\ "vimxmltaginfo": {\ 'tag1': ['Menu info', 'Long information visible in preview window']},\ 'vimxmlattrinfo': {\ 'attrofchild': ['Menu info', 'Long information visible in preview window']}}

This example would be put in the "autoload/xml/crippled.vim" file and couldhelp to write this file:

<tag1 attroftag1b="valueofattr1">    <childoftag1a attrofchild>            &amp; &lt;    </childoftag1a>    <childoftag1b attrofchild="5">        <childoftag1a>            &gt; &apos; &quot;        </childoftag1a>    </childoftag1b></tag1>

In the example four special elements are visible:

1. "vimxmlentities" - a special key with List containing entities of this XML dialect.2. If the list containing possible values of attributes has one element and this element is equal to the name of the attribute this attribute will be treated as boolean and inserted as "attrname" and not as 'attrname="'3. "vimxmltaginfo" - a special key with a Dictionary containing tag names as keys and two element List as values, for additional menu info and the long description.4. "vimxmlattrinfo" - special key with Dictionary containing attribute names as keys and two element List as values, for additional menu info and long description.

Note: Tag names in the data file MUST not contain a namespace description.Check xsl.vim for an example.Note: All data and functions are publicly available as globalvariables/functions and can be used for personal editing functions.

DTD -> Vimdtd2vim

Onwww is the scriptdtd2vim which parses DTD and creates an XML data filefor Vim XML omni completion.

dtd2vim:https://www.vim.org/scripts/script.php?script_id=1462

Check the beginning of that file for usage details.The script requires perl and:

perlSGML:https://savannah.nongnu.org/projects/perlsgml

Commands

:XMLns{name} [{namespace}]:XMLns

Vim has to know which data file should be used and with which namespace. Forloading of the data file and connecting data with the proper namespace use:XMLns command. The first (obligatory) argument is the name of the data(xhtml10s, xsl). The second argument is the code of namespace (h, xsl). Whenused without a second argument the dialect will be used as default - withoutnamespace declaration. For example to use XML completion in .xsl files:

:XMLns xhtml10s:XMLns xsl xsl

:XMLent{name}:XMLent

By default entities will be completed from the data file of the defaultnamespace. The XMLent command should be used in case when there is no defaultnamespace:

:XMLent xhtml10s

Usage

While used in this situation (after declarations from previous part, | iscursor position):

<|

Will complete to an appropriate XHTML tag, and in this situation:

<xsl:|

Will complete to an appropriate XSL tag.

The script xmlcomplete.vim, provided through theautoload mechanism,has the xmlcomplete#GetLastOpenTag() function which can be used in XML filesto get the name of the last open tag (b:unaryTagsStack has to be defined):

:echo xmlcomplete#GetLastOpenTag("b:unaryTagsStack")

8. Insert mode commandsinserting

The following commands can be used to insert new text into the buffer. Theycan all be undone and repeated with the "." command.

a
aAppend text after the cursor [count] times. If thecursor is in the first column of an empty line Insertstarts there. But not when'virtualedit' is set!

A
AAppend text at the end of the line [count] times.For using "A" in Visual block mode seev_b_A.

<insert>oriinsert<Insert>iInsert text before the cursor [count] times.When usingCTRL-O in Insert modei_CTRL-O the countis not supported.

I
IInsert text before the first non-blank in the line[count] times.When the 'H' flag is present in'cpoptions' and theline only contains blanks, insert start just beforethe last blank.For using "I" in Visual block mode seev_b_I.

gI
gIInsert text in column 1 [count] times.

gi
giInsert text in the same position as where Insert modewas stopped last time in the current buffer.This uses the'^ mark. It's different from "`^i"when the mark is past the end of the line.The position is corrected for inserted/deleted lines,but NOT for inserted/deleted characters.When the:keepjumps command modifier is used the'^mark won't be changed.

o
oBegin a new line below the cursor and insert text,repeat [count] times.

O
OBegin a new line above the cursor and insert text,repeat [count] times.

These commands are used to start inserting text. You can end insert mode with<Esc>. Seemode-ins-repl for the other special characters in Insert mode.The effect of [count] takes place after Insert mode is exited.

The followingdefault-mappings insert text, but stay in normal mode:

]<Space>
]<Space>Insert an empty line below the cursor without leavingNormal mode, repeat [count] times.

[<Space>
[<Space>Insert an empty line above the cursor without leavingNormal mode, repeat [count] times.

When'autoindent' is on, the indent for a new line is obtained from theprevious line. When'smartindent' or'cindent' is on, the indent for a lineis automatically adjusted for C programs.

'formatoptions' can be set to copy the comment leader when opening a newline.

'textwidth' can be set to the maximum width for a line. When a line becomestoo long when appending characters a line break is automatically inserted.

9. Ex insert commandsinserting-ex

:a:append:{range}a[ppend][!]Insert several lines of text below the specifiedline. If the{range} is missing, the text will beinserted after the current line.Adding [!] toggles'autoindent' for the time thiscommand is executed.

:i:in:insert:{range}i[nsert][!]Insert several lines of text above the specifiedline. If the{range} is missing, the text will beinserted before the current line.Adding [!] toggles'autoindent' for the time thiscommand is executed.

These two commands will keep on asking for lines, until you type a linecontaining only a ".". Watch out for lines starting with a backslash, seeline-continuation.

Text typed after a "|" command separator is used first. So the followingcommand in ex mode:

:a|onetwo.:visual

appends the following text, after the cursor line:

onetwo

NOTE: These commands cannot be used with:global or:vglobal.":append" and ":insert" don't work properly in between ":if" and":endif", ":for" and ":endfor", ":while" and ":endwhile".

:start:startinsert:star[tinsert][!]Start Insert mode (orTerminal-mode in aterminalbuffer) just after executing this command.Works like typing "i" in Normal mode. When the ! isincluded it works like "A", append to the line.Otherwise insertion starts at the cursor position.Note that when using this command in a function orscript, the insertion only starts after the functionor script is finished.This command does not work from:normal.

:stopi:stopinsert:stopi[nsert]Stop Insert mode orTerminal-mode as soon aspossible. Works like typing<Esc> in Insert mode.Can be used in an autocommand, example:

:au BufEnter scratch stopinsert

replacing-ex:startreplace:startr[eplace][!]Start Replace mode just after executing this command.Works just like typing "R" in Normal mode. When the! is included it acts just like "$R" had been typed(ie. begin replace mode at the end-of-line). Other-wise replacement begins at the cursor position.Note that when using this command in a function orscript that the replacement will only start afterthe function or script is finished.

:startgreplace
:startg[replace][!]Just like:startreplace, but use Virtual Replacemode, like withgR.

10. Inserting a fileinserting-file

:r:re:read:r[ead] [++opt] [name]Insert the file [name] (default: current file) belowthe cursor.See++opt for the possible values of [++opt].

:{range}r[ead] [++opt] [name]Insert the file [name] (default: current file) belowthe specified line.See++opt for the possible values of [++opt].

:r!:read!:[range]r[ead] [++opt] !{cmd}Execute{cmd} and insert its standard output belowthe cursor or the specified line. A temporary file isused to store the output of the command which is thenread into the buffer.'shellredir' is used to savethe output of the command, which can be set to includestderr or not.{cmd} is executed like with ":!{cmd}",any '!' is replaced with the previous command:!.See++opt for the possible values of [++opt].

These commands insert the contents of a file, or the output of a command,into the buffer. They can be undone. They cannot be repeated with the "."command. They work on a line basis, insertion starts below the line in whichthe cursor is, or below the specified line. To insert text above the firstline use the command ":0r{name}".

After the ":read" command, the cursor is left on the first non-blank in thefirst new line. If in Ex mode, then the cursor is left on the last newline (sorry, this is Vi compatible).

If a file name is given with ":r", it becomes the alternate file. This can beused, for example, when you want to edit that file instead: ":e! #". This canbe switched off by removing the 'a' flag from the'cpoptions' option.

Of the [++opt] arguments one is specifically for ":read", the ++edit argument.This is useful when the ":read" command is actually used to read a file intothe buffer as if editing that file. Use this command in an empty buffer:

:read ++edit filename

The effect is that the'fileformat','fileencoding','bomb', etc. options areset to what has been detected for "filename". Note that a single empty lineremains, you may want to delete it.

file-read
The'fileformat' option sets the<EOL> style for a file:

'fileformat' characters name

"dos"<CR><NL> or<NL> DOS format "unix"<NL> Unix format "mac"<CR> Mac format

If'fileformat' is "dos", a<CR> in front of an<NL> is ignored and aCTRL-Zat the end of the file is ignored.

If'fileformat' is "mac", a<NL> in the file is internally represented by a<CR>. This is to avoid confusion with a<NL> which is used to represent a<NUL>. SeeCR-used-for-NL.

If the'fileformats' option is not empty Vim tries to recognize the type of<EOL> (seefile-formats). However, the'fileformat' option will not bechanged, the detected format is only used while reading the file.A similar thing happens with'fileencodings'.

On non-Win32 systems the message "[dos format]" is shown if a file is read inDOS format, to remind you that something unusual is done.On Macintosh and Win32 the message "[unix format]" is shown if a file is readin Unix format.On non-Macintosh systems, the message "[mac format]" is shown if a file isread in Mac format.

An example on how to use ":r !":

:r !uuencode binfile binfile

This command reads "binfile", uuencodes it and reads it into the currentbuffer. Useful when you are editing e-mail and want to include a binaryfile.

read-messages
When reading a file Vim will display a message with information about the readfile. In the table is an explanation for some of the items. The others areself explanatory. Using the long or the short version depends on the'shortmess' option.

longshortmeaning

[readonly]{RO}the file is write protected[fifo/socket]using a stream[fifo]using a fifo stream[socket]using a socket stream[CR missing]reading with "dos"'fileformat' and aNL without a preceding CR was found.[NL found]reading with "mac"'fileformat' and aNL was found (could be "unix" format)[long lines split]at least one line was split in two[NOT converted]conversion from'fileencoding' to'encoding' was desired but notpossible[converted]conversion from'fileencoding' to'encoding' done[READ ERRORS]not all of the file could be read

2. Special special keys

cursor one line up

3. 'textwidth' and 'wrapmargin' options

4. 'expandtab', 'softtabstop' and 'smarttab' options

5. Replace mode

6. Virtual Replace mode

7. Insert mode completion