starting.txt ForVim version 9.1. Last change: 2025 Feb 27VIM REFERENCE MANUAL by Bram MoolenaarStarting Vimstarting1. Vim argumentsvim-arguments2. Vim on theAmigastarting-amiga3. Running eVimevim-keys4. Initializationinitialization5.$VIM and$VIMRUNTIME$VIM6. Suspendingsuspend7. Exitingexiting8. Saving settingssave-settings9. Views and Sessionsviews-sessions10. Theviminfo fileviminfo-file==============================================================================1. Vim argumentsvim-argumentsMost often, Vimis started to edita single file with the commandvim filename-vimMore generally, Vimis started with:vim [option | filename] ..Option arguments and file name arguments can be mixed, and any number of themcan be given. However, watch out foroptions that take an argument.For compatibility withvariousVi versions, seecmdline-arguments.Exactly one out of the following five items may be used to choose how tostart editing:-file---filenameOne or more file names. The first one will be the currentfile and read into the buffer. The cursor will be positionedon the first line of the buffer.To avoida file namestarting witha '-' being interpretedasan option, precede thearglist with "--", e.g.:vim -- -filenameAll arguments after the "--" will be interpretedas file names,no otheroptions or "+command" argument can follow.For behavior ofquotes on MS-Windows, seewin32-quotes.---This argument can mean two things, depending on whetherExmodeis to be used.Starting inNormal mode:vim -ex -v -Start editinga new buffer, whichis filled with textthatis read from stdin. The commands that would normally beread from stdin will now be read from stderr. Example:find . -name "*.c" -print | vim -The buffer will be markedas modified, so that you arereminded to save the text when trying to exit. If you don'tlike that,put this these lines in your vimrc:" Don't set 'modified' when reading from stdinau StdinReadPost * set nomodifiedStarting inEx mode:ex -vim -e -exim -vim -EStart editing in silent mode. See-s-ex.-t-tag-t{tag}A tag. "tag"is looked up in thetags file, the associatedfile becomes the current file, and the associated commandisexecuted. Mostly thisis used forC programs, in whichcase"tag" oftenisa function name. The effectis that the filecontaining that function becomes the current file and thecursoris positioned on the start of the function (seetags).-q-qf-q[errorfile]QuickFix mode. The file with the name[errorfile]is readand the first erroris displayed. Seequickfix.If[errorfile]is not given, the'errorfile' optionis usedfor the file name. See'errorfile' for the default value.(nothing)Without one of the four items above, Vim will start editinganew buffer. It's empty and doesn't havea file name.Thestartup mode can be changed by using another name instead of "vim", whichis equal to giving options:ex vim-e Start inEx mode (seeEx-mode).exexim vim-E Start in improvedEx mode (seeEx-mode).exim (normally not installed)view vim-R Start in read-only mode (see-R).viewgvim vim-g Start theGUI (seegui).gvimgex vim -eg Start theGUI inEx mode.gexgview vim -Rg Start theGUI in read-only mode.gviewrvim vim-Z Like "vim", but in restricted mode (see-Z)rvimrview vim -RZ Like "view", but in restricted mode.rviewrgvim vim -gZ Like "gvim", but in restricted mode.rgvimrgview vim -RgZ Like "gview", but in restricted mode.rgviewevim vim-y Easy Vim: set'insertmode' (see-y)evimeview vim -yR Like "evim" in read-only modeeviewvimdiff vim-d Start indiff modediff-modegvimdiff vim -gd Start indiff modediff-modeAdditional characters may follow, they are ignored. For example, you can have"gvim-8" to start the GUI. Youmust have an executable by that name then, ofcourse.On Unix, you would normally have one executable called "vim", and links fromthe different startup-names to that executable. If your system does notsupport links and youdo not want to have several copies of the executable,you could use an alias instead. For example, inaC shell descendant:alias view vim -Ralias gvim vim -gstartup-optionsThe option arguments may be given in any order. Single-letteroptions can becombined after one dash. There can be no option arguments after the "--"argument.OnVMS all option arguments are assumed to be lowercase, unless preceded witha slash. Thus "-R" meansrecovery and "-/R" readonly.--help-h--help-?-?-hGive usage (help) message and exit.Seeinfo-message about capturing the text.--version--versionPrint version information and exit. Same outputas for:version command.Seeinfo-message about capturing the text.--noplugin--nopluginSkip loading plugins. Resets the'loadplugins' option.Note that the-u argument may also disable loading plugins:argument load: vimrc files plugins defaults.vim(nothing) yesyes yes-u NONE nono no-u DEFAULTS nono yes-u NORC noyes no--noplugin yesno yes--startuptime{fname}--startuptimeDuringstartup write timingmessages to the file{fname}.This can be used to find out where timeis spent while loadingyour .vimrc, plugins and opening the first file.When{fname} already exists newmessages are appended.{only available when compiled with the+startuptimefeature}--literal--literalTake file names literally, don't expand wildcards. Not neededfor Unix, because Vim always takes file names literally (theshell expands wildcards).Applies to all the names, also the ones that come before thisargument.-++[num]The cursor will be positioned on line "num" for the firstfile being edited. If "num"is missing, the cursor will bepositioned on the last line.-+/+/{pat}The cursor will be positioned on the first line containing"pat" in the first file being edited (seepattern for theavailable search patterns). The search startsat the cursorposition, which can be the first line or the cursor positionlast used fromviminfo. To forcea search from the firstline use "+1 +/pat".+{command}-+c-c-c{command}{command} will be executed after the first file has beenread (and afterautocommands and modelines for that file havebeen processed). "command"is interpretedas anEx command.If the "command" contains spaces,itmust be enclosed indoublequotes (this depends on the shell thatis used).Example:vim "+set si" main.cvim "+find stdio.h"vim -c "set ff=dos" -c wq mine.makNote: You can use up to 10 "+" or "-c" arguments ina Vimcommand. They are executed in the order given.A "-S"argument countsasa "-c" argumentas well.--cmd{command}--cmd{command} will be executed before processing anyvimrc file.Otherwise,it acts like-c{command}. You can use up to 10 ofthese commands, independently from "-c" commands.-S-S{file}The{file} will be sourced after the first file has been read.Thisis aneasy way todo the equivalent of:-c "source {file}"It can be mixed with "-c" arguments and repeated like "-c".The limit of 10 "-c" arguments applies hereas well.{file} cannot start witha "-".Do not use this for runningascript todo some work and exitVim, you won't see error messages. Use-u instead.-SWorks like "-S Session.vim". Only when usedas the lastargument or when another "-" option follows.-r-rRecovery mode. Withouta file name argument,alist ofexisting swap filesis given. Witha file name,a swap fileis read to recovera crashed editing session. Seecrash-recovery.-L-LSameas -r.-R-RReadonly mode. The'readonly' option will be set for all thefiles being edited. You can still edit the buffer, but willbe prevented from accidentally overwritinga file. If youforgot that you are inView mode and did make some changes,you can overwritea file by adding an exclamationmark totheEx command,as in ":w!". The'readonly' option can bereset with ":set noro" (see theoptions chapter,options).Subsequent edits will not be done in readonly mode. Callingthe executable "view" has the same effectas the-R argument.The'updatecount' option will be set to 10000, meaning thatthe swap file will not be updated automatically very often.See-M for disallowing modifications.-m-mModifications not allowed to be written. The'write' optionwill be reset, so thatwriting filesis disabled. However,the'write' option can be set to enablewriting again.-M-MModifications not allowed. The'modifiable' option will bereset, so that changes are not allowed. The'write' optionwill be reset, so thatwriting filesis disabled. However,the'modifiable' and'write'options can be set to enablechanges and writing.-Zrestricted-modeE145E981-ZRestricted mode. All commands that make use of an externalshell are disabled. This includes suspending withCTRL-Z,":sh", filtering, thesystem() function, backtick expansionand libcall().Also disallowed aredelete(),rename(),mkdir(),job_start(),setenv() etc.Interfaces, suchas Python,Ruby and Lua, are also disabled,since they could be used to execute shell commands.Perl usesthe Safe module.ForUnix restricted modeis used when the last part of $SHELLis "nologin" or "false".Note that the user may still finda loophole to executeashell command,it has only been made difficult.-g-gStart Vim inGUI mode. Seegui. For the opposite see-v.-v-vStartEx inVi mode. Only makesa difference when theexecutableis called "ex" or "gvim". Forgvim theGUIis notstarted if possible.-e-eStart Vim inEx mode, seeEx-mode. Only makesa differencewhen the executableis not called "ex".-E-EStart Vim in improvedEx modegQ. Only makesa differencewhen the executableis not called "exim".-s-ex-sSilent or batch mode. Only when Vim was startedas "ex" orwhen preceded with the "-e" argument. Otherwise, see-s,which does take an argument while this use of "-s" doesn't.To be used when Vimis used to executeEx commands froma fileinstead ofa terminal. Switches off most prompts andinformative messages. Also warnings and error messages.The output of these commandsis displayed (to stdout)::print:list:number:set to display option values.When'verbose'is non-zero,messages are printed (fordebugging, to stderr).'term' and $TERM are not used.If Vim appears to be stuck, try typing "qa!<Enter>". Youdon't geta prompt, thus you can't see Vimis waiting for youto type something.Initializations are skipped (except the ones given with the"-u" argument).Example:vim -e -s < thefilter thefileFor the opposite, to seeerrors from the script, execute thefile with the-u flag:vim -u thefilter thefile-b-bBinary mode. File I/O will only recognize<NL> to separatelines. The'expandtab' option will be reset. The'textwidth'optionis set to 0.'modeline'is reset. The'binary' optionis set. Thisis done after reading the vimrc/exrc files butbefore reading any file in the arglist. See alsoedit-binary.-l-lLisp mode. Sets the'lisp' and'showmatch'options on.-A-AArabic mode. Sets the'arabic' option on. {only whencompiled with the+arabic features (which include+rightleft), otherwise, Vim gives an error messageand exits}-F-FThis was used forFarsi mode, which has been removed.Seefarsi.txt.-H-HHebrew mode. Sets the'hkmap' and'rightleft'options on.{only when compiled with the+rightleft feature, otherwise,Vim gives an error message and exits}-Vverbose-V[N]Verbose. Sets the'verbose' option to [N] (default: 10).Messages will be given for each file thatis ":source"d andfor reading orwritingaviminfo file. Can be used to findout whatis happening uponstartup and exit.Example:vim -V8 foobar-V[N]{filename}Like-V and set'verbosefile' to{filename}. The resultisthatmessages are not displayed but written to the file{filename}.{filename}must not start witha digit.Example:vim -V20vimlog foobar--log{filename}--logStart logging and write entries to{filename}.This works like calling `ch_logfile({filename},'ao')` veryearly during startup.{only available with the |+eval| and |+channel| feature}-D-DDebugging. Go to debugging mode when executing the firstcommand froma script.debug-mode{not available when compiled without the |+eval| feature}-C-CCompatible mode. Sets the'compatible' option. You can usethis to get'compatible', even thougha.vimrc file exists.Keep in mind that the command ":set nocompatible" in someplugin orstartupscript overrules this, so you mayend upwith'nocompatible' anyway. To find out, use::verbose set compatible?Several plugins won't work with'compatible' set. You maywant to setit afterstartup this way:vim "+set cp" filenameAlso seecompatible-default.-N-NNot compatible mode. Resets the'compatible' option. You canuse this to get'nocompatible', when thereis no.vimrc fileor when using "-u NONE".Also seecompatible-default.-yeasy-yEasy mode. Implied forevim andeview. Starts with'insertmode' set and behaves likea click-and-type editor.This sources thescript $VIMRUNTIME/evim.vim. Mappings areset up to work like most click-and-type editors, seeevim-keys. TheGUIis started when available.-n-nNo swap file will be used. Recovery aftera crash will beimpossible. Handy if you want toview or edita file onavery slow medium (e.g.,a floppy).Can also be done with ":set updatecount=0". You can switchiton again by setting the'updatecount' option to some value,e.g., ":set uc=100".NOTE: Don't combine-n with -b, making -nb, because that hasadifferent meaning:-nb.'updatecount'is set to0 AFTER executing commands fromavimrc file, but before theGUI initializations. Thusitoverridesa setting for'updatecount' inavimrc file, but notinagvimrc file. Seestartup.When you want to reduce accesses to the disk (e.g., foralaptop), don't use "-n", but set'updatetime' and'updatecount' to very big numbers, and type ":preserve" whenyou want to save your work. This way you keep the possibilityfor crash recovery.-o-o[N]OpenN windows, split horizontally. If [N]is not given,onewindowis opened for every file givenas argument. Ifthereis not enough room, only the first few files getawindow. If there are morewindows than arguments, the lastfewwindows will be editing an empty file.-O-O[N]OpenN windows, split vertically. Otherwise, it's like -o.If both the-o and the-O option are given, the last one onthe command line determines how thewindows will be split.-p-p[N]OpenNtab pages. If [N]is not given, onetab pageis openedfor every file givenas argument. The maximumis set with'tabpagemax' pages (default 10). If there are moretab pagesthan arguments, the last fewtab pages will be editing anempty file. Also seetabpage.-T-T{terminal}Set theterminal type to "terminal". This influences thecodes that Vim will send to your terminal. Thisis normallynot needed, because Vim will be able to find out what typeofterminal you are using. (Seeterminal-info.)--not-a-term--not-a-termTells Vim that the user knows that the input and/or outputisnot connected toa terminal. This will avoid the warning andthe two second delay that would happen.Also avoids the "Reading from stdin..."as wellas the"N files to edit" message.--gui-dialog-file{name}--gui-dialog-fileWhen using the GUI, instead of showinga dialog, write thetitle and message of thedialog to file{name}. The fileiscreated or appended to. Only useful for testing, to avoidthat the test gets stuck onadialog that can't be seen.Without theGUI the argumentis ignored.--ttyfail--ttyfailWhen the stdin or stdoutis notaterminal (tty) then exitright away.-d-dStart indiff mode, likevimdiff.{not available when compiled without the |+diff| feature}-d{device}Only on theAmiga and when not compiled with the+difffeature. Works like "-dev".-dev-dev{device}Only on the Amiga: The{device}is opened to be used forediting.Normally you would use this to set thewindow position andsize: "-d con:x/y/width/height", e.g.,"-d con:30/10/600/150". But you can also useit to startediting on another device, e.g., AUX:.-f-fGUI: Do not disconnect from the program that started Vim.'f' stands for "foreground". If omitted, theGUI forksa newprocess and exits the current one. "-f" should be used whengvimis started bya program that will wait for the editsession to finish (e.g., mail or readnews). If you wantgvimnever to fork, include 'f' in'guioptions' in yourgvimrc.Careful: You can use "-gf" to start theGUI in the foreground,but "-fg"is used to specify the foreground color.gui-forkAmiga: Do not restart Vim to opena new window. Thisoption should be used when Vimis started bya program thatwill wait for the edit session to finish (e.g., mail orreadnews). Seeamiga-window.MS-Windows: This optionis not supported. However, whenrunning Vim with an installed vim.bat or gvim.bat fileitworks.--nofork--noforkGUI: Do not fork. Sameas-f.-uE282-u{vimrc}The file{vimrc}is read for initializations. Most otherinitializations are skipped; seeinitialization.This can be used to start Vim ina special mode, with specialmappings and settings.A shell alias can be used to makethiseasy to use. For example, inaC shell descendant:alias vimc 'vim -u ~/.c_vimrc \!*'And ina Bash shell:alias vimc='vim -u ~/.c_vimrc'Also consider using autocommands; seeautocommand.When{vimrc}is equal to "NONE" (all uppercase), allinitializations from files and environmentvariables areskipped, including reading thegvimrc file when theGUIstarts. Loading pluginsis also skipped.When{vimrc}is equal to "NORC" (all uppercase), this has thesame effectas "NONE", but loading pluginsis not skipped.When{vimrc}is equal to "DEFAULTS" (all uppercase), this hasthe same effectas "NONE", but thedefaults.vimscriptisloaded, which will also set'nocompatible'. Also see--clean.Using the "-u" argument with another argument than DEFAULTShas the side effect that the'compatible' option will be on bydefault. This can have unexpected effects. See'compatible'.-UE230-U{gvimrc}The file{gvimrc}is read for initializations when theGUIstarts. OtherGUI initializations are skipped. When{gvimrc}is equal to "NONE", no fileis read forGUI initializationsatall.gui-initException: Reading the system-wide menu fileis always done.-i-i{viminfo}The file "viminfo"is used instead of the defaultviminfofile. If the name "NONE"is used (all uppercase), noviminfofileis read or written, even if'viminfo'is set or when":rv" or ":wv" are used. See alsoviminfo-file.--clean--cleanSimilar to "-u DEFAULTS-U NONE-i NONE":- initializations from files and environmentvariablesis skipped-'runtimepath' and'packpath' are set to excludehome directory entries (does not happen with-u DEFAULTS).- thedefaults.vimscriptis loaded, which implies'nocompatible': use Vim defaults- nogvimrcscriptis loaded- noviminfo fileis read or writtenNote thata following "-u" argument overrules the effect of"-u DEFAULTS".-x-xUseencryption to read/write files. Will prompt fora key,whichis then stored in the'key' option. All writes willthen use this key to encrypt the text. The '-x' argumentisnot needed when readinga file, because thereisa check ifthe file thatis being read has been encrypted, and Vim asksfora key automatically.encryption{only available when compiled with the |+cryptv| feature}-X-XDo not try connecting to theX server to get the currentwindow title and copy/paste using theX clipboard. Thisavoidsa longstartup time when running Vim inaterminalemulator and the connection to theX serveris slow.See--startuptime to find out if this affects you.Only makesa difference onUnix or VMS, when compiled with the+X11 feature. Otherwise, it's ignored.To disable the connection only for specific terminals, see the'clipboard' option.When theX11Session Management Protocol (XSMP) handler hasbeen built in, the-X option also disables that connectionasit, too, may have undesirable delays.When the connectionis desired later anyway (e.g., forclient-server messages), call theserverlist() function.This does not enable the XSMP handler though.-s-s{scriptin}Thescript file "scriptin"is read. The characters in thefile are interpretedas if you had typed them. The same canbe done with the command ":source!{scriptin}". If theendof the fileis reached before the editor exits, furthercharacters are read from the keyboard. Only works when notstarted inEx mode, see-s-ex. See alsocomplex-repeat.-w_nr-w{number}-w{number}Set the'window' option to{number}.-w-w{scriptout}All the characters that you type are recorded in the file"scriptout", until you exit Vim. Thisis useful if you wantto createascript file to be used with "vim-s" or":source!". When the "scriptout" file already exists, newcharacters are appended. See alsocomplex-repeat.{scriptout} cannot start witha digit.If you want to record whatis typed ina human readable form,you can usech_logfile(). It adds "raw key input" lines.Also see--log.-W-W{scriptout}Like -w, butdo not append, overwrite an existing file.--remote [+{cmd}]{file}...Open the{file} in another Vim thatfunctionsasa server.Any non-file argumentsmust come before this.See--remote.--remote-silent [+{cmd}]{file}...Like --remote, but don't complain if thereis no server.See--remote-silent.--remote-wait [+{cmd}]{file}...Like --remote, but wait for the server to finish editing thefile(s).See--remote-wait.--remote-wait-silent [+{cmd}]{file}...Like --remote-wait, but don't complain if thereis no server.See--remote-wait-silent.--servername{name}Specify the name of the Vim server to send to or to become.See--servername.--remote-send{keys}Send{keys} toa Vim server and exit.See--remote-send.--remote-expr{expr}Evaluate{expr} in another Vim thatfunctionsasa server.The resultis printed on stdout.See--remote-expr.--serverlistOutputalist of Vim server names and exit. See--serverlist.--socketid{id}--socketidGTK+GUI Vim only. Makegvim try to use GtkPlug mechanism, sothatit runs inside another window. Seegui-gtk-socketidfor details.--windowid{id}--windowidWin32GUI Vim only. Makegvim try to use thewindow{id}asaparent, so thatit runs inside that window. Seegui-w32-windowid for details.--echo-wid--echo-widGTK+GUI Vim only. Makegvim echo the Window ID on stdout,which can be used to rungvim ina kpart widget. The formatof the output is:WID: 12345\n--role{role}--roleGTK+ 2GUI only. Set the role of the mainwindow to{role}.Thewindow role can be used byawindow manager to uniquelyidentifya window, in order to restorewindow placement andsuch. The--role argumentis passed automatically whenrestoring the session on login. Seegui-gnome-session-P{parent-title}-PMDIE671E672Win32 only: Specify the title of the parent application. Whenpossible, Vim will run in anMDIwindow inside theapplication.{parent-title}must appear in thewindow title of the parentapplication. Make sure thatitis specific enough.Note that the implementationis still primitive. It won'twork with all applications and the menu doesn't work.-nb-nb-nb={fname}-nb:{hostname}:{addr}:{password}Attempt connecting to Netbeans and become an editor server forit. The second formspecifiesa file to read connection infofrom. The third formspecifies the hostname, address andpassword for connecting to Netbeans.netbeans-run{only available when compiled with the+netbeans_intgfeature; if not then-nb will make Vim exit}If the executableis called "view", Vim will start in Readonly mode. Thisisuseful if you can makea hard or symbolic link from "view" to "vim".Starting in Readonly mode can also be done with "vim-R".If the executableis called "ex", Vim will start in "Ex" mode. This meansitwill accept only ":" commands. But when the "-v" argumentis given, Vim willstart inNormal mode anyway.Additional arguments are available onUnix like systems when compiled withX11GUI support. Seegui-resources.==============================================================================2. Vim on theAmigastarting-amigaStarting Vim from the Workbenchworkbench-------------------------------Vim can be started from the Workbench by clicking on its icon twice. It willthen start with an empty buffer.Vim can be started to edit one or more files by usinga "Project" icon. The"Default Tool" of the iconmust be the full pathname of the Vim executable.The name of the ".info" filemust be the sameas the name of the text file.By clicking on this icon twice, Vim will be started with the file nameascurrent file name, which will be read into the buffer (ifit exists). You canedit multiple files by pressing theshift key while clicking on icons, andclicking twice on the last one. The "Default Tool" for all these iconsmustbe the same.Itis not possible to give arguments to Vim, other than file names, from theworkbench.Vimwindowamiga-window----------Vim will run in the CLIwindow whereit was started. If Vim was started withthe "run" or "runback" command, or if Vim was started from the workbench,itwill openawindow of its own.Technical detail:To open the newwindowa little trickis used. As soonas Vimrecognizes thatit does not run ina normal CLI window,it willcreateascript file in "t:". Thisscript file contains the samecommandas the one Vim was started with, and an "endcli" command.Thisscript fileis then executed witha "newcli" command (the "c:run"and "c:newcli" commands are required for this to work). Thescriptfile will hang around until reboot, or until you delete it. Thismethodis required to get the ":sh" and ":!" commands to workcorrectly. But when Vim was started with the-f option (foregroundmode), thismethodis not used. The reason for thisis thatwhena program starts Vim with the-f optionit will wait for Vim toexit. With thescript trick, the calling program does not know whenVim exits. The-f option can be used when Vimis started bya mailprogram which also waits for the edit session to finish. Asaconsequence, the ":sh" and ":!" commands are not available when the-f optionis used.Vim will automatically recognize thewindow size and react towindowresizing. UnderAmigaDOS 1.3,itis advised to use the fastfonts program,"FF", to speed up display redrawing.==============================================================================3. Running eVimevim-keysEVim runs Vimas click-and-type editor. Thisis very unlike the originalViidea. Butit helps for people that don't use Vim often enough to learn thecommands. Hopefully they will find out that learning to useNormal modecommands will make their editing much more effective.In Evim theseoptions are changed from their default value::set nocompatibleUse Vim improvements:set insertmodeRemain inInsert mode most of the time:set hiddenKeep invisiblebuffers loaded:setbackupKeepbackup files (not for VMS):set backspace=2Backspace over everything:set autoindentauto-indent new lines:set history=50keep 50 lines ofEx commands:set rulershow the cursor position:set incsearchshow matches halfway typingapattern:set mouse=ause the mouse in all modes:set hlsearchhighlight all matches fora searchpattern:set whichwrap+=<,>,[,]<Left> and<Right> wrap around line breaks:set guioptions-=anon-Unix only: don'tdo auto-selectKey mappings:<CTRL-Q>quit, using:confirm prompt if there are changes<Down>moves by screen lines rather than file lines<Up>idemQdoes "gq", formatting, instead ofEx mode<BS>inVisual mode: deletes the selectionCTRL-XinVisual mode: Cut toclipboard<S-Del>idemCTRL-CinVisual mode: Copy toclipboard<C-Insert>idemCTRL-VPastes from theclipboard (in any mode)<S-Insert>idemCTRL-ZundoCTRL-Yredo<M-Space>system menuCTRL-Aselect all<C-Tab>next window,CTRL-Ww<C-F4>close window,CTRL-WcAdditionally:- ":behave mswin"is used:behave-syntax highlightingis enabled-filetype detectionis enabled,filetype plugins and indentingis enabled- ina text file'textwidth'is set to 78One hint: If you want togo toNormal mode to be able to typea sequence ofcommands, useCTRL-L.i_CTRL-LThereis no way to stop "easy mode", you need to exit Vim.==============================================================================4. InitializationinitializationstartupThissectionis about the non-GUI version of Vim. Seegui-fork foradditionalinitialization whenstarting the GUI.At startup, Vim checks environmentvariables and files and sets valuesaccordingly. Vim proceeds in this order:1. Set the'shell' and'term' optionSHELLCOMSPECTERMThe environment variable SHELL, ifit exists,is used to set the'shell' option. On Win32, theCOMSPEC variableis usedifSHELLis not set.The environment variable TERM, ifit exists,is used to set the'term'option. However,'term' will change later whenstarting theGUI (step8 below).2. Process the argumentsTheoptions and file names from the command that start Vim areinspected.The-V argument can be used to display or log what happens next,useful for debugging the initializations.The--cmd arguments are executed.Buffers are created for all files (but not loaded yet).3. ExecuteEx commands, from environmentvariables and/or filesAn environment variableis readas oneEx command line, where multiplecommandsmust be separated with'|' or "<NL>".vimrcexrcA file that containsinitialization commandsis calleda "vimrc" file.Each line inavimrc fileis executedas anEx command line. Itissometimes also referred toas "exrc" file. They are the same type offile, but "exrc"is whatVi always used, "vimrc"isa Vim specificname. Also seevimrc-intro.Places for your personal initializations:Unix$HOME/.vimrc, $HOME/.vim/vimrcor $XDG_CONFIG_HOME/vim/vimrcMS-Windows$HOME/_vimrc, $HOME/vimfiles/vimrcor $VIM/_vimrcAmigas:.vimrc, home:.vimrc, home:vimfiles:vimrcor $VIM/.vimrcHaiku$HOME/config/settings/vim/vimrcThe files are searched in the order specified above and only the firstone thatis foundis read.RECOMMENDATION: Put all your Vim configuration stuff in the$HOME/.vim/ directory ($HOME/vimfiles/ for MS-Windows). That makesiteasy to copyit to another system.If Vim was started with "-u filename", the file "filename"is used.All following initializations until 4. are skipped.$MYVIMRC and$MYVIMDIR are not set (but$MYVIMDIR will be set, if'rtp'isupdated)."vim-u NORC" can be used to skip these initializations withoutreadinga file. "vim-u NONE" also skips loading plugins.-uIf Vim was started inEx mode with the "-s" argument, all followinginitializations until 4. are skipped. Only the "-u" optionisinterpreted.evim.vim a. If Vim was startedasevim oreview or with the-y argument, thescript $VIMRUNTIME/evim.vim will be loaded.system-vimrc b. For Unix, MS-Windows, VMS,Macintosh andAmiga the systemvimrc fileis read for initializations. The path of this fileis shown with the":version" command. Mostly it's "$VIM/vimrc".Note that this fileisALWAYS read in'compatible' mode, since the automatic resetting of'compatible'is only done later. Adda ":set nocp" command if youlike. For theMacintosh the $VIMRUNTIME/macmap.vimis read.VIMINIT.vimrc_vimrcEXINIT.exrc_exrc$MYVIMRC$MYVIMDIR c. Five places are searched for initializations. The first that existsis used, the others are ignored. The$MYVIMRC environment variableisset to the file that was first found, unless$MYVIMRC was already setwhen using VIMINIT. The$MYVIMDIR environment variableisset to the personal'rtp' directory, howeveritis not verifiedthat the directory actually exists.I The environment variableVIMINIT (see alsocompatible-default)(*) The value of $VIMINITis usedas anEx command line.II The uservimrc file(s): "$HOME/.vimrc" (for Unix)(*) "$HOME/.vim/vimrc" (for Unix)(*) "$XDG_CONFIG_HOME/vim/vimrc" (for Unix)(*) "s:.vimrc" (for Amiga)(*) "home:.vimrc" (for Amiga)(*) "home:vimfiles:vimrc" (for Amiga)(*) "$VIM/.vimrc" (for Amiga)(*) "$HOME/_vimrc" (for Win32)(*) "$HOME/vimfiles/vimrc" (for Win32)(*) "$VIM/_vimrc" (for Win32)(*) "$HOME/config/settings/vim/vimrc"(for Haiku)(*)Note: ForUnix and Amiga, when ".vimrc" does not exist,"_vimrc"is also tried, incase anMS-DOS compatible filesystemis used. ForMS-Windows ".vimrc"is checked after"_vimrc", incase long file names are used.Note: For Win32, "$HOME"is checked first. If no "_vimrc" or".vimrc"is found there, "$VIM"is tried. See$VIM for when$VIMis not set.III The environment variable EXINIT. The value of $EXINITis usedas anEx command line.IV The userexrc file(s). Sameas for the uservimrc file, but with "vimrc" replaced by "exrc". But only one of ".exrc" and "_exrc"is used, depending on the system. And without the(*)!V The defaultvimrc file, $VIMRUNTIME/defaults.vim. This sets upoptions values and has "syntax on" and "filetype on" commands, whichis what most new users will want. Seedefaults.vim. d. If the'exrc' optionis on (whichis NOT the default), the currentdirectoryis searched for three files. The first that existsis used,the others are ignored.- The file ".vimrc" (for Unix, Amiga)(*) "_vimrc" (for Win32)(*)- The file "_vimrc" (for Unix, Amiga)(*) ".vimrc" (for Win32)(*)- The file ".exrc" (for Unix, Amiga) "_exrc" (for Win32)(*) Using this file or environment variable will cause'compatible' to be off by default. Seecompatible-default.Note: When using themzscheme interface,itis initialized after loading thevimrc file. Changing'mzschemedll' later has no effect.4. Load theplugin scripts.load-pluginsThis does the sameas the command::runtime! plugin/**/*.vimThe resultis that all directories in the'runtimepath' option will besearched for the "plugin" sub-directory and all files ending in ".vim"will be sourced (in alphabetical order per directory), also insubdirectories.However, directories in'runtimepath' ending in "after" are skippedhere and only loaded after packages, see below.Loading plugins won't be done when:- The'loadplugins' option was reset inavimrc file.- The--noplugin command line argumentis used.- The--clean command line argumentis used.- The "-u NONE" command line argumentis used-u.- When Vim was compiled without the+eval feature.Note that using "-c 'set noloadplugins'" doesn't work, because thecommands from the command line have not been executed yet. You canuse "--cmd 'set noloadplugins'" or "--cmd 'set loadplugins'"--cmd.Packages are loaded. These are plugins,as above, but found in the"start" directory of each entry in'packpath'. Everyplugin directoryfoundis added in'runtimepath' and then the plugins are sourced. Seepackages.The plugins scripts are loaded,as above, but now only the directoriesending in "after" are used.Note that'runtimepath' will have changedifpackages have been found, but that should not adda directoryending in "after".5. Set'shellpipe' and'shellredir'The'shellpipe' and'shellredir'options are set according to thevalue of the'shell' option, unless they have been set before.This means that Vim will figure out the values of'shellpipe' and'shellredir' for you, unless you have set them yourself.6. Set'updatecount' to zero, if "-n" command argument used.7. Set binaryoptionsIf the "-b" flag was given to Vim, theoptions for binary editing willbe set now. See-b.8. PerformGUI initializationsOnly whenstarting "gvim", theGUI initializations will be done. Seegui-init.9. Read theviminfo fileIf the'viminfo' optionis not empty, theviminfo fileis read. Seeviminfo-file.10. Read thequickfix fileIf the "-q" flag was given to Vim, thequickfix fileis read. If thisfails, Vim exits.11. Open allwindowsWhen the-o flag was given,windows will be opened (but notdisplayed yet).When the-p flag was given,tab pages will be created (but notdisplayed yet).When switching screens,it happens now. Redrawing starts.If the "-q" flag was given to Vim, the first erroris jumped to.Buffers for allwindows will be loaded, without triggeringBufAddautocommands.12. Executestartup commandsIfa "-t" flag was given to Vim, thetagis jumped to.The commands given with the-c and+cmd arguments are executed.If the'insertmode' optionis set,Insert modeis entered.Thestarting flagis reset, has("vim_starting") will now return zero.Thev:vim_did_enter variableis set to 1.TheVimEnterautocommands are executed.The$MYVIMRC or$MYGVIMRC environment variable will be set to the first foundvimrc and/orgvimrc file while$MYVIMDIRis set to the users personal runtimedirectory'rtp' (typically the first entry in'runtimepath'). If'rtp'changes,$MYVIMDIR will be updated.Note: These environmentvariables resolve symbolic links, but'rtp' does not.Some hints on using initializationsStandard setup:Createavimrc file to set the default settings and mappings for all your editsessions. Putit ina place so thatit will be found by 3b.:~/.vimrc(Unix)s:.vimrc(Amiga)$VIM\_vimrc(Win32)~/config/settings/vim/vimrc (Haiku)Note that creatingavimrc file will cause the'compatible' option to be offby default. Seecompatible-default.Local setup:Put all commands that you need for editinga specific directory only intoavimrc file and placeit in that directory under the name ".vimrc"("_vimrc"for Win32).NOTE: To make Vim look for these special files you have to turnon the option'exrc'. Seetrojan-horse too.System setup:This only applies if you are managingaUnix system with several users andwant to set the defaults for all users. Createavimrc file with commandsfor default settings and mappings andputit in the place thatis given withthe ":version" command.Saving the current state of Vim to a fileWhenever you have changed values ofoptions or when you have createdamapping, then you may want to save them inavimrc file for later use. Seesave-settings about saving the current state of settings toa file.Avoiding setup problems for Vi usersVi uses the variableEXINIT and the file "~/.exrc". So if youdo not want tointerfere with Vi, then use the variableVIMINIT and the file "vimrc" instead.Amiga environment variablesOn the Amiga, two types of environmentvariables exist. The ones set with theDOS 1.3 (or later) setenv command are recognized. See the AmigaDos 1.3manual. The environmentvariables set with the old Manx Set command (beforeversion 5.0) are not recognized.MS-Windows line separatorsOn MS-Windows, Vim assumes that all thevimrc files have<CR><NL> pairsasline separators. This will give problems if you havea file with only<NL>sand havea line like ":map xx yy^M". The trailing ^M will be ignored.Vi compatible default valuecompatible-defaultWhen Vim starts, the'compatible' optionis on. This will be used when Vimstarts its initializations. Butas soon as:-a uservimrc fileis found, or-avimrc file in the current directoryis found, or- the "VIMINIT" environment variableis set, or- the "-N" command line argumentis given, or- the "--clean" command line argumentis given, or- thedefaults.vimscriptis loaded, or-agvimrc file was found,then the option will be set to'nocompatible'.Note that this does NOT happen whena system-widevimrc file was found.This has the side effect of setting or resetting otheroptions (see'compatible'). But only theoptions that have not been set or reset will bechanged. This has the same effect like the value of'compatible' had thisvalue whenstarting Vim.'compatible'is NOT reset, anddefaults.vimis not loaded:- when Vim was started with the-u command line argument, especially with "-u NONE", or- when started with the-C command line argument, or- when the name of the executable ends in "ex". (This has been done to make Vim behave like "ex", whenitis startedas "ex")But thereisa side effect of setting or resetting'compatible'at the momenta.vimrc fileis found: Mappings are interpreted the moment they areencountered. This makesa difference when using things like "<CR>". If themappings depend ona certain value of'compatible', set or resetit beforegiving the mapping.Defaults without a .vimrc filedefaults.vimE1187If Vimis started normally and no uservimrc fileis found, the$VIMRUNTIME/defaults.vimscriptis loaded. This will set'compatible' off,switch onsyntax highlighting anda few more things. See thescript fordetails.NOTE: thisis done since Vim 8.0, not in Vim 7.4. (it was added inpatch 7.4.2111 to be exact).This should work well for new Vim users. If you create your own .vimrc,itisrecommended to add these lines somewhere near the top:unlet! skip_defaults_vimsource $VIMRUNTIME/defaults.vimThen Vim works like before you hada .vimrc.Copying $VIMRUNTIME/vimrc_example.vim to your.vimrcis another way todothis. Alternatively, you can copydefaults.vim to your.vimrc and modifyit(but then you won't get updates whenit changes).If you don't like some of the defaults, you can still sourcedefaults.vim andrevert individual settings. See thedefaults.vim file for hints on how torevert each item.skip_defaults_vimIf you usea system-widevimrc and don't wantdefaults.vim to change settings,set the "skip_defaults_vim" variable. If this was set and you want to loaddefaults.vim from your .vimrc, first unlet skip_defaults_vim,as in theexample above.xdg-base-dir$XDG_CONFIG_HOMEXDG Base Directory SpecificationThe XDG Base Directory Specification aims to definea standard location forconfiguration files used by applications. Thisis mainly done to preventthe legacy behavior of dumping everything into the user'shome directory.The specification can be found onlineathttps://specifications.freedesktop.org/basedir-spec/latest/The location of this standard configuration directoryis configurable by theuser, using an environment variable but should also give fallback incase thosevariables weren't set.Thisis not an exhaustivelist of those directories: Environment varDefault locationDescription$XDG_CACHE_HOME $HOME/.cacheEphemeral data files$XDG_CONFIG_HOME $HOME/.configConfiguration files$XDG_DATA_HOME $HOME/.local/sharePersistent data files$XDG_STATE_HOME $HOME/.local/stateState data filesVim will only use the$XDG_CONFIG_HOME directory, the others are not(yet) used for itsvarious configuration and state files.xdg-vimrcVim, onUnix systems, will lookat$XDG_CONFIG_HOME/vim/vimrc for itsconfiguration (seevimrc) butit will sourceit only if no otherinitialization fileis found in$HOME or$HOME/.vim (thus making thisfeature backward compatible). However, if you want to migrate to use$XDG_CONFIG_HOME/vim/ directory, you will have to move away your~/.vimrcand~/.vim/vimrc file.xdg-runtimeWhen thexdg-vimrcis used the'runtimepath' and'packpath'options will bemodified accordingly to respect thexdg-base-dir: "$XDG_CONFIG_HOME/vim,$VIMRUNTIME,/after,$XDG_CONFIG_HOME/vim/after"Avoiding trojan horsestrojan-horseWhile reading the "vimrc" or the "exrc" file in the current directory, somecommands can be disabled for security reasons by setting the'secure' option.Thisis always done when executing the command fromatags file. Otherwise,it would be possible that you accidentally useavimrc ortags file thatsomebody else created and contains nasty commands. The disabled commands arethe ones that starta shell, the ones that write toa file, and ":autocmd".The ":map" commands are echoed, so you can see which keys are being mapped.If you want Vim to execute all commands ina localvimrc file, youcan reset the'secure' option in theEXINIT orVIMINIT environment variable orin the global "exrc" or "vimrc" file. Thisis not possible in "vimrc" or"exrc" in the current directory, for obvious reasons.OnUnix systems, this only happens if you are not the owner of thevimrc file. Warning: If you unpack an archive that containsavimrc orexrcfile,it will be owned by you. You won't have the security protection. Checkthevimrc file before you start Vim in that directory, or reset the'exrc'option. SomeUnix systems allowa user todo "chown" ona file. This makesit possible for another user to createa nastyvimrc and make you the owner.Be careful!When usingtag search commands, executing the search command (the lastpart of the line in thetags file)is always done in secure mode. This worksjust like executinga command froma vimrc/exrc in the current directory.If Vim startup is slowslow-startIf Vim takesa long time to start up, use the--startuptime argument to findout what happens. There area few common causes:- If theUnix version was compiled with theGUI and/orX11 (check the output of ":version" for "+GUI" and "+X11"),it may need to load shared libraries and connect to theX11 server. Try compilinga version withGUI andX11 disabled. This also should make the executable smaller. Use the-X command line argument to avoid connecting to theX server when running ina terminal.- If you have "viminfo" enabled, the loading of theviminfo file may takea while. You can find out if thisis the problem by disablingviminfo fora moment (use the Vim argument "-i NONE",-i). Try reducing the number of lines stored inaregister with ":set viminfo='20,<50,s10".viminfo-file.Intro message:introWhen Vim starts withouta file name, an introductory messageis displayed (forthose who don't know what Vim is). Itis removedas soonas the displayisredrawn in any way. To see the message again, use the ":intro" command (ifthereis not enough room, you will see only part of it). To avoid theintro message on startup, add the 'I' flag to'shortmess'.info-messageThe--help and--version arguments cause Vim to printa message and thenexit. Normally the messageis sent to stdout, thus can be redirected toafile with:vim --help >fileFrom inside Vim::read !vim --helpWhen using gvim,it detects thatit might have been started from the desktop,withoutaterminal to showmessages on. Thisis detected when both stdout andstderr are nota tty. This breaks the ":read" command,as used in the exampleabove. To makeit work again, set'shellredir' to ">" instead of the default">&"::set shellredir=>:read !gvim --helpThis still won't work for systems wheregvim does not use stdoutat allthough.==============================================================================5.$VIM and$VIMRUNTIME$VIMThe environment variable "$VIM"is used to locatevarious user files for Vim,suchas the userstartupscript ".vimrc". This depends on the system, seestartup.To avoid the need for every user to set the$VIM environment variable, Vimwill try to get the value for$VIM in this order:1. The value defined by the$VIM environment variable. You can use this to make Vim look ina specific directory for its support files. Example:setenv VIM /home/paul/vim2. The path from'helpfile'is used, unlessit contains some environment variable too (the defaultis "$VIMRUNTIME/doc/help.txt": chicken-egg problem). The file name("help.txt" or any other)is removed. Then trailing directory names are removed, in this order: "doc", "runtime" and "vim{version}" (e.g., "vim82").3. ForWin32 Vim tries to use the directory name of the executable. Ifit ends in "/src", thisis removed. Thisis useful if you unpacked the .zip file in some directory, and adjusted the search path to find the vim executable. Trailing directory names are removed, in this order: "runtime" and "vim{version}" (e.g., "vim82").4. ForUnix the compile-time defined installation directoryis used (see the output of ":version").Once Vim has done this once,it will set the$VIM environment variable. Tochangeit later, usea ":let" command like this::let $VIM = "/home/paul/vim/"$VIMRUNTIMEThe environment variable "$VIMRUNTIME"is used to locatevarious supportfiles, suchas the on-line documentation and files used forsyntaxhighlighting. For example, the mainhelp fileis normally"$VIMRUNTIME/doc/help.txt".You don't normally set$VIMRUNTIME yourself, but let Vim figureit out. Thisis the order used to find the value of $VIMRUNTIME:1. If the environment variable$VIMRUNTIMEis set,itis used. You can use this when the runtime files are in an unusual location.2. If "$VIM/vim{version}" exists,itis used.{version}is the version number of Vim, without any '-' or '.'. For example: "$VIM/vim82". Thisis the normal value for $VIMRUNTIME.3. If "$VIM/runtime" exists,itis used.4. The value of$VIMis used. Thisis for backwards compatibility with older versions.5. When the'helpfile' optionis set and doesn't containa '$', its valueis used, with "doc/help.txt" removed from the end.For Unix, when thereisa compiled-in default for$VIMRUNTIME (check theoutput of ":version"), steps 2, 3 and 4 are skipped, and the compiled-indefaultis used after step 5. This means that the compiled-in defaultoverrules the value of $VIM. Thisis useful if$VIMis "/etc" and the runtimefiles are in "/usr/share/vim/vim82".Once Vim has done this once,it will set the$VIMRUNTIME environment variable.To changeit later, usea ":let" command like this::let $VIMRUNTIME = "/home/piet/vim/vim82"Incase you need the value of$VIMRUNTIME ina shell (e.g., forascript thatgreps in thehelp files) you might be able to use this:VIMRUNTIME=$(vim -es '+put=$VIMRUNTIME|print|quit!')Don't set$VIMRUNTIME to an empty value, some things may stop working.==============================================================================6. SuspendingsuspendiconizeiconiseCTRL-Zv_CTRL-ZCTRL-ZSuspend Vim, like ":stop".Works inNormal and inVisual mode. InInsert andCommand-line mode, theCTRL-Zis insertedasa normalcharacter. InVisual mode Vim goes back toNormalmode.Note: ifCTRL-Z undoesa change seemswin.vim.:sus[pend][!]or:sus:suspend:st:stop:st[op][!]Suspend Vim.If the '!'is not given and'autowrite'is set, everybuffer with changes anda file nameis written out.If the '!'is given or'autowrite'is not set, changedbuffers are not written, don't forget to bring Vimback to the foreground later!In the GUI, suspendingis implementedas iconising gvim. In MS-Windows,gvimis minimized.On manyUnix systems,itis possible tosuspend Vim withCTRL-Z. Thisis onlypossible inNormal andVisual mode (see next chapter,vim-modes). Vim willcontinue if you makeit the foregroundjob again. On other systems,CTRL-Zwill starta new shell. Thisis the sameas the ":sh" command. Vim willcontinue if you exit from the shell.In theX Window System environment, the selectionis disowned when Vimsuspends. This means you can't pasteit in another application (since Vimisgoing to sleep, an attempt to get the selection would make the program hang).==============================================================================7. ExitingexitingThere are several ways to exit Vim:- Close the lastwindow with:quit. Only when there are no changes.- Close the lastwindow with:quit!. Also when there are changes.- Close allwindows with:qall. Only when there are no changes.- Close allwindows with:qall!. Also when there are changes.- Use:cquit. Also when there are changes.When using:cquit or when there was an error message Vim exits with exitcode 1. Errors can be avoided by using:silent! or with:catch.==============================================================================8. Saving settingssave-settingsMostly you will edit yourvimrc files manually. This gives you the greatestflexibility. There area few commands to generateavimrc file automatically.You can use these filesas they are, or copy/paste lines to include in anothervimrc file.:mk:mkexrc:mk[exrc][file]Write current key mappings and changedoptions to[file] (default ".exrc" in the current directory),unlessit already exists.:mk[exrc]![file]Always write current key mappings and changedoptions to[file] (default ".exrc" in the currentdirectory).:mkv:mkvi:mkvimrc:mkv[imrc][!][file]Like ":mkexrc", but the defaultis ".vimrc" in thecurrent directory. The ":version" commandis alsowritten to the file.These commands will write ":map" and ":set" commands toa file, in sucha waythat when these commands are executed, the current key mappings andoptionswill be set to the same values. Theoptions'columns','endofline','fileformat','key','lines','modified','scroll','term','textmode','ttyfast' and'ttymouse' are not included, because these areterminal or filedependent.Note that theoptions'binary','paste' and'readonly' areincluded, this might not always be what you want.When special keys are used in mappings, the'cpoptions' option will betemporarily set to its Vim default, to avoid the mappings to bemisinterpreted. This makes the file incompatible with Vi, but makes sureitcan be used with different terminals.Only global mappings are stored, not mappings local toa buffer.A commonmethodis to usea default ".vimrc" file, make some modificationswith ":map" and ":set" commands and write the modified file. First read thedefault ".vimrc" in witha command like ":source ~piet/.vimrc.Cprogs", changethe settings and then save them in the current directory with ":mkvimrc!". Ifyou want to make this file your default .vimrc, moveit to yourhome directory(on Unix), s: (Amiga) or$VIM directory (MS-Windows). You could also useautocommandsautocommand and/or modelinesmodeline.vimrc-option-exampleIf you only want to adda single option setting to your vimrc, you can usethese steps:1. Edit yourvimrc file with Vim.2. Play with the option until it's right. E.g., try out different values for'guifont'.3. Appenda line to set the value of the option, using theexpressionregister '=' to enter the value. E.g., for the'guifont' option: o:set guifont=<C-R>=&guifont<CR><Esc> [<C-R>isaCTRL-R,<CR>isa return,<Esc>is theescape key] You need toescape special characters, esp. spaces.Note that when you createa.vimrc file, this can influence the'compatible'option, which has several side effects. See'compatible'.":mkvimrc", ":mkexrc" and ":mksession" write the command to set or reset the'compatible' option to the output file first, because of these side effects.==============================================================================9. Views and Sessionsviews-sessionsThisis introduced in sections21.4 and21.5 of the user manual.Viewview-fileAViewisa collection of settings that apply to one window. You can saveaView and when you restoreit later, the textis displayed in the same way.Theoptions and mappings in thiswindow will also be restored, so that you cancontinue editing like when theView was saved.Sessionsession-fileASession keeps the Views for all windows, plus the global settings. You cansaveaSession and when you restoreit later thewindow layout looks the same.You can useaSession to quickly switch between different projects,automatically loading the files you were last working on in that project.Views and Sessions area nice addition to viminfo-files, which are used toremember information for all Views and Sessions togetherviminfo-file.You can quickly start editing witha previously savedView orSession with the-S argument:vim -S Session.vimAll thisis{not available when compiled without the |+mksession| feature}.:mks:mksession:mks[ession][!][file]Writea Vimscript that restores the current editingsession.When [!]is included, an existing fileis overwritten.When[file]is omitted, "Session.vim"is used.The output of ":mksession"is like ":mkvimrc", but additional commands areadded to the file. Which ones depends on the'sessionoptions' option. Theresulting file, when executed witha ":source" command:1. Restores global mappings and options, if'sessionoptions' contains "options". Script-local mappings will not be written.2. Restores globalvariables that start with anuppercaseletter and containat least onelowercase letter, if'sessionoptions' contains "globals".3. Closes allwindows in the currenttab page, except the current one; closes alltab pages except the current one (this results in currently loadedbuffers to be unloaded, some may become hidden if'hidden'is set or otherwise specified); wipes out the current buffer, ifitis empty and unnamed.4. Restores the current directory, if'sessionoptions' contains "curdir", or sets the current directory to where theSession file is, if'sessionoptions' contains "sesdir".5. RestoresGUI Vimwindow position, if'sessionoptions' contains "winpos".6. Restores screen size, if'sessionoptions' contains "resize".7. Reloads the buffer list, with the last cursor positions. If'sessionoptions' contains "buffers" then allbuffers are restored, including hidden and unloaded buffers. Otherwise, onlybuffers inwindows are restored.8. Restores allwindows with the same layout. If'sessionoptions' contains "help",helpwindows are restored. If'sessionoptions' contains "blank",windows editinga buffer withouta name will be restored. If'sessionoptions' contains "winsize" and no (help/blank)windows were left out, thewindow sizes are restored (relative to the screen size). Otherwise, thewindows are just given sensible sizes.9. Restores the Views for all the windows,as with:mkview. But'sessionoptions'is used instead of'viewoptions'.10. Ifa file exists with the same nameas theSession file, but ending in "x.vim" (for eXtra), executes thatas well. You can use *x.vim files to specify additional settings and actions associated witha given Session, suchas creating menu items in theGUI version.After restoring the Session, the full filename of your currentSessionisavailable in the internal variable "v:this_session"this_session-variable.An example mapping: :nmap <F2> :wa<Bar>exe "mksession! " .. v:this_session<CR>:so ~/sessions/This saves the current Session, and starts off the command to load another.A session includes alltab pages, unless "tabpages" was removed from'sessionoptions'.tab-pageTheSessionLoadPost autocmd eventis triggered aftera session fileisloaded/sourced.SessionLoad-variableWhile the session fileis loading, the SessionLoad global variableis set to1. Plugins can use this to postpone some work until theSessionLoadPost eventis triggered.:mkvie:mkview:mkvie[w][!][file]Writea Vimscript that restores the contents of thecurrent window.When [!]is included, an existing fileis overwritten.When[file]is omitted orisa number from 1 to 9,anameis generated and'viewdir' prepended. When thelast path part of'viewdir' does not exist, thisdirectoryis created. E.g., when'viewdir'is"$VIM/vimfiles/view" then "view"is created in"$VIM/vimfiles".An existing fileis always overwritten then. Use:loadview to load thisview again.When[file]is the name ofa file ('viewdir'is notused),a command to edit the fileis added to thegenerated file.The output of ":mkview" contains these items:1. The argumentlist used in the window. When the global argumentlistis used,itis reset to the global list. Theindex in the argumentlistis also restored.2. The file being edited in the window. If thereis no file, thewindowis made empty.3. Restore mappings,abbreviations andoptions local to the window, if'viewoptions' contains "options" or "localoptions". Only option values that are local to the current buffer and the currentwindow are restored. When storing theviewas part ofa session and "options"is in'sessionoptions', global values for localoptions will be stored too.4. Restorefolds when using manualfolding and'viewoptions' contains "folds". Restore manually opened and closed folds.5. The scroll position and the cursor position in the file. Doesn't work very well when there are closed folds.6. The local current directory, ifitis different from the global current directory and'viewoptions' contains "curdir".Note that Views and Sessions are not perfect:- They don't restore everything. For example, defined functions,autocommands and ":syntax on" are not included. Things likeregister contents and command linehistory are in viminfo, not in Sessions or Views.- Global option values are only set when they differ from the default value. When the current valueis not the default value, loadingaSession will not setit back to the default value. Localoptions will be set back to the default value though.- Existing mappings will be overwritten without warning. An existingmapping may cause an error for ambiguity.- When storing manualfolds and when storing manually opened/closed folds, changes in the file between saving and loading theview will messit up.- The Vimscriptis not very efficient. But still faster than typing the commands yourself!:lo:loadview:lo[adview][nr]Load theview for the current file. When[nr]isomitted, theview stored with ":mkview"is loaded.When[nr]is specified, theview stored with ":mkview[nr]"is loaded.The combination of ":mkview" and ":loadview" can be used to store up to tendifferent views ofa file. These are remembered in the directory specifiedwith the'viewdir' option. The views are stored using the file name. Ifafileis renamed or accessed througha (symbolic) link, theview will not befound.You might want to clean up your'viewdir' directory now and then.To automatically save and restore views for *.c files:au BufWinLeave *.c mkviewau BufWinEnter *.c silent loadview==============================================================================10. Theviminfo fileviminfoviminfo-fileE136E575E576E577If you exit Vim and later startit again, you would normally losea lot ofinformation. Theviminfo file can be used to remember that information, whichenables you to continue where you left off.Thisis introduced insection21.3 of the user manual.Theviminfo fileis used to store:- The command line history.- The searchstring history.- The input-line history.-Contents of non-empty registers.- Marks for several files.- File marks, pointing to locations in files.- Last search/substitutepattern (for 'n' and '&').- The buffer list.- Global variables.Theviminfo fileis not supported when the+viminfo feature has beendisabledat compile time.You could also useaSession file. The differenceis that theviminfo filedoes not depend on what you are working on. There normallyis only oneviminfo file.Session files are used to save the state ofa specific editingSession. You could have severalSession files, one for each project you areworking on. Viminfo andSession files together can be used to effectivelyenter Vim and directly start working in your desired setup.session-fileviminfo-readWhen Vimis started and the'viminfo' optionis non-empty, the contents oftheviminfo file are read and the info can be used in the appropriate places.Thev:oldfiles variableis filled. The marks are not read inatstartup(but file marks are). Seeinitialization for how to set the'viminfo'option upon startup.viminfo-writeWhen Vim exits and'viminfo'is non-empty, the infois stored in theviminfofile (it's actually merged with the existing one, if one exists). The'viminfo' optionisastring containing information about what info should bestored, and containslimits on how much should be stored (see'viminfo').Merging happens in two ways. Most items that have been changed or set in thecurrent Vim session are stored, and what was not changedis filled from whatis currently in theviminfo file. For example:- Vim sessionA reads the viminfo, which contains variable START.- Vim sessionB does the same- Vim sessionA sets thevariables AAA and BOTH and exits- Vim sessionB sets thevariables BBB and BOTH and exitsNow theviminfo will have: START-it was in theviminfo and wasn't changed in sessionA orB AAA- value from session A, sessionB keptit BBB- value from sessionB BOTH- value from session B, value from sessionAis lostviminfo-timestampFor some itemsatimestampis used to keep the last changed version. Hereitdoesn't matter in which sequence Vim sessions exit, the newest item(s) arealways kept. Thisis used for:- The command line history.- The searchstring history.- The input-line history.-Contents of non-empty registers.- The jump list.- File marks.Thetimestamp feature was added before Vim 8.0. Older versions of Vim,starting with 7.4.1131, will keep the items with timestamp, but not use them.Thus, when using both an older anda newer version of Vim, the most recentdata will be kept.Notes for Unix:- The file protection for theviminfo file will be set to prevent other users from being able to read it, becauseit may contain any text or commands that you have worked with.- If you want to share theviminfo file with other users (e.g. when you "su" to another user), you can make the file writable for the group or everybody. Vim will preserve this whenreplacing theviminfo file. Be careful, don't allow just anybody to read and write yourviminfo file!- Vim will not overwriteaviminfo file thatis not writable by the current "real" user. This helps for when you did "su" to become root, but your$HOMEis still set toa normal user'shome directory. Otherwise, Vim would createaviminfo file owned by root that nobody else can read.- Theviminfo file cannot bea symbolic link. Thisis to avoid security issues.Marks are stored for each file separately. Whena fileis read and'viminfo'is non-empty, the marks for that file are read from theviminfo file.NOTE:The marks are only written whenexiting Vim, whichis fine because marks areremembered for all the files you have opened in the current editing session,unless ":bdel"is used. If you want to save the marks fora file that you areabout toabandon with ":bdel", use ":wv". The '[' and ']' marks are notstored, but the'"'mark is. The'"'markis very useful for jumping to thecursor position when the file was last exited. No marks are saved for filesthat start with anystring given with the "r" flag in'viminfo'. This can beused to avoid saving marks for files on removable media (forMS-Windows youwould use "ra:,rb:", forAmiga "rdf0:,rdf1:,rdf2:").Thev:oldfiles variableis filled with the file names that theviminfo filehas marks for.viminfo-file-marksUppercase marks ('A to 'Z) are stored whenwriting theviminfo file. Thenumbered marks ('0 to '9) area bit special. When theviminfo fileis written(whenexiting or with the ":wviminfo" command),'0is set to the current cursorposition and file. The old'0is moved to '1, '1 to '2, etc. Thisresembles what happens with the "1 to "9 delete registers. If the currentcursor positionis already present in'0 to '9,itis moved to '0, to avoidhaving the same position twice. The resultis that with "'0", you can jumpback to the file and line where you exited Vim. Todo that right away, tryusing this command:vim -c "normal '0"InaC shell descendant, you could make an alias for it:alias lvim vim -c '"'normal "'"0'"'Fora Bash-like shell:alias lvim='vim -c "normal '\''0"'Use the "r" flag in'viminfo' to specify for which files no marks should beremembered.VIMINFO FILE NAMEviminfo-file-name- The default name of theviminfo fileis "$HOME/.viminfo" for Unix, "s:.viminfo" for Amiga, "$HOME\_viminfo" for Win32. For Win32, when$HOMEis not set, "$VIM\_viminfo"is used. When$VIMis also not set, "c:\_viminfo"is used.- The 'n' flag in the'viminfo' option can be used to specify anotherviminfo file name'viminfo'.- The "-i" Vim argument can be used to set another file name,-i. When the file name givenis "NONE" (all uppercase), noviminfo fileis ever read or written. Also not for the commands below!- The'viminfofile' option can be used like the "-i" argument. In fact, the value from the "-i" argumentis stored in the'viminfofile' option.- For the commands below, another file name can be given, overriding the default and the name given with'viminfo' or "-i" (unless it's NONE).CHARACTER ENCODINGviminfo-encodingThe text in theviminfo fileis encodedas specified with the'encoding'option. Normally you will always work with the same'encoding' value, andthis works just fine. However, if you read theviminfo file with anothervalue for'encoding' than whatit was written with, some of the text(non-ASCII characters) may be invalid. If thisis unacceptable, add the 'c'flag to the'viminfo' option::set viminfo+=cVim will then attempt to convert the text in theviminfo file from the'encoding' valueit was written with to the current'encoding' value. Thisrequires Vim to be compiled with the+iconv feature. Filenames are notconverted.MANUALLY READING AND WRITINGviminfo-read-writeTwo commands can be used to read and write theviminfo file manually. Thiscan be used to exchangeregisters between two running Vim programs: Firsttype ":wv" in one and then ":rv" in the other.Note that if theregisteralready contained something, then ":rv!" would be required. Also note,however, that this means everything will be overwritten with information fromthe first Vim, including the command line history, etc.Theviminfo file itself can be edited by hand too, although we suggest youstart with an existing one to get the format right. Itis reasonablyself-explanatory once you're in there. This can be useful in order tocreatea second file, say "~/.my_viminfo", which could contain certainsettings that you always want when you first start Vim. For example, youcan preloadregisters with particular data, orput certain commands in thecommand line history.A line in your.vimrc file like:rviminfo! ~/.my_viminfocan be used to load this information. You could even have different viminfosfor different types of files (e.g.,C code) and load them based on the filename, using the ":autocmd" command (see:autocmd).viminfo-errorsWhen Vim detects an error while readingaviminfo file,it will not overwritethat file. If there are more than 10 errors, Vim stops reading theviminfofile. This was done to avoid accidentally destroyinga file when the filename of theviminfo fileis wrong. This could happen when accidentally typing"vim-i file" when you wanted "vim-R file" (yes, somebody accidentally didthat!). If you want to overwriteaviminfo file with an error in it, you willeither have to fix the error, or delete the file (while Vimis running, somost of the information will be restored).:rv:rviminfoE195:rv[iminfo][!][file]Read fromviminfo file[file] (default: seeviminfo-file-name above).If [!]is given, then any information thatisalready set (registers, marks,v:oldfiles, etc.)will be overwritten. "E195" may be given, when'viminfofile' has been set to "NONE".:wv:wviminfoE137E138E574E886E929:wv[iminfo][!][file]Write toviminfo file[file] (default: seeviminfo-file-name above).This command has no effect when'viminfofile' has beenset to "NONE".The information in the fileis first read in to makeamerge between old and new info. When [!]is used,the old informationis not read first, only theinternal infois written. If'viminfo'is empty, marksfor up to 100 files will be written.When you get error "E929: Too manyviminfo tempfiles", check that no old temp files were left behind(e.g. ~/.viminf*) and that you can write in thedirectory of the .viminfo file.:ol:oldfiles:ol[dfiles]List the files that have marks stored in theviminfofile. Thislistis read onstartup and only changesafterwards with:rviminfo!. Also seev:oldfiles.The number can be used withc_#<.The output can be filtered with:filter, e.g.:filter /\.vim/ oldfilesThe filtering happens on the file name.{only when compiled with the |+eval| feature}:bro[wse] ol[dfiles][!]List file namesas with:oldfiles, and then promptfora number. When the numberis valid that file fromthelistis edited.If you get thepress-enter prompt you can press "q"and still get the prompt to entera file number.Use [!] toabandona modified buffer.abandon{not when compiled with tiny features} vim:tw=78:ts=8:noet:ft=help:norl: