diff options
Diffstat (limited to 'runtime/doc/starting.txt')
| -rw-r--r-- | runtime/doc/starting.txt | 175 |
1 files changed, 71 insertions, 104 deletions
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index 0ded6a9060..d0faeb9cb7 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -9,20 +9,20 @@ Starting Vim *starting* Type |gO| to see the table of contents. ============================================================================== -1. Vim arguments *vim-arguments* +Nvim arguments *vim-arguments* -Most often, Vim is started to edit a single file with the command +Most often, Nvim is started to edit a single file with the command: > - nvim filename *-vim* + nvim filename -More generally, Vim is started with: +More generally, Nvim is started with: > nvim [option | filename] .. Option arguments and file name arguments can be mixed, and any number of them can be given. However, watch out for options that take an argument. -The following items may be used to choose how to start editing: +The following items decide how to start editing: *-file* *---* filename One or more file names. The first one will be the current @@ -231,9 +231,8 @@ argument. -b Binary mode. File I/O will only recognize <NL> to separate lines. The 'expandtab' option will be reset. The 'textwidth' option is set to 0. 'modeline' is reset. The 'binary' option - is set. This is done after reading the init.vim/exrc files - but before reading any file in the arglist. See also - |edit-binary|. + is set. This is done after reading the |vimrc| but before + reading any file in the arglist. See also |edit-binary|. *-l* -l Lisp mode. Sets the 'lisp' and 'showmatch' options on. @@ -398,7 +397,7 @@ argument. primary listen address |v:servername| to {addr}. |serverstart()| ============================================================================== -2. Initialization *initialization* *startup* +Initialization *initialization* *startup* At startup, Vim checks environment variables and files and sets values accordingly. Vim proceeds in this order: @@ -414,45 +413,47 @@ accordingly. Vim proceeds in this order: The |-V| argument can be used to display or log what happens next, useful for debugging the initializations. -3. Execute Ex commands, from environment variables and/or files - An environment variable (e.g. $VIMINIT) is read as one Ex command - line, where multiple commands must be separated with '|' or <NL>. +3. Wait for UI to connect. + Nvim started with |--embed| waits for the UI to connect before + proceeding to load user configuration. + +4. Load user config (execute Ex commands from files, environment, …). + $VIMINIT environment variable is read as one Ex command line (separate + multiple commands with '|' or <NL>). *config* *init.vim* *vimrc* *exrc* - A file that contains initialization commands is generically called - a "vimrc" or config file. Each line in a vimrc file is executed as an - Ex command line. See also |vimrc-intro| and |base-directories|. + A file containing init commands is generically called a "vimrc" or + "config". Each line in such a file is executed as an Ex command. + |vimrc-intro| |base-directories| - The Nvim config file is named "init.vim", located at: + The Nvim config file is "init.vim", located at: Unix ~/.config/nvim/init.vim Windows ~/AppData/Local/nvim/init.vim - Or if |$XDG_CONFIG_HOME| is defined: + or if |$XDG_CONFIG_HOME| is defined: $XDG_CONFIG_HOME/nvim/init.vim - If Nvim was started with "-u filename", the file "filename" is used. - All following initializations until 4. are skipped. $MYVIMRC is not - set. + If Nvim was started with "-u {file}" then {file} is used as the config + and all initializations until 5. are skipped. $MYVIMRC is not set. "nvim -u NORC" can be used to skip these initializations without reading a file. "nvim -u NONE" also skips plugins and syntax highlighting. |-u| - If Nvim was started with |-es|, all following initializations until 4. - are skipped. + If Nvim was started with |-es| all initializations until 5. are + skipped. *system-vimrc* *sysinit.vim* a. The system vimrc file is read for initializations. If nvim/sysinit.vim file exists in one of $XDG_CONFIG_DIRS, it will be - used. Otherwise, the system vimrc file is used. The path of this file - is shown with the ":version" command. Mostly it's "$VIM/sysinit.vim". + used. Otherwise the system vimrc file is used. The path of this file + is given by the |:version| command. Usually it's "$VIM/sysinit.vim". *VIMINIT* *EXINIT* *$MYVIMRC* - b. Four places are searched for initializations. The first that exists - is used, the others are ignored. The $MYVIMRC environment variable is - set to the file that was first found, unless $MYVIMRC was already set - and when using VIMINIT. - - Environment variable $VIMINIT, used as an Ex command line. - - User |config| file: $XDG_CONFIG_HOME/nvim/init.vim. - - Other config file: {xdg_config_dir}/nvim/init.vim where - {xdg_config_dir} is one of the directories in $XDG_CONFIG_DIRS. - - Environment variable $EXINIT, used as an Ex command line. + b. Locations searched for initializations, in order of preference: + - $VIMINIT environment variable (Ex command line). + - User |config|: $XDG_CONFIG_HOME/nvim/init.vim. + - Other config: {dir}/nvim/init.vim where {dir} is any directory + in $XDG_CONFIG_DIRS. + - $EXINIT environment variable (Ex command line). + |$MYVIMRC| is set to the first valid location unless it was already + set or when using $VIMINIT. c. If the 'exrc' option is on (which is NOT the default), the current directory is searched for two files. The first that exists is used, @@ -460,7 +461,7 @@ accordingly. Vim proceeds in this order: - The file ".nvimrc" - The file ".exrc" -4. Enable filetype and indent plugins. +5. Enable filetype and indent plugins. This does the same as the commands: > :runtime! filetype.vim :runtime! ftplugin.vim @@ -468,13 +469,13 @@ accordingly. Vim proceeds in this order: < Skipped if ":filetype … off" was called or if the "-u NONE" command line argument was given. -5. Enable syntax highlighting. +6. Enable syntax highlighting. This does the same as the command: > :runtime! syntax/syntax.vim < Skipped if ":syntax off" was called or if the "-u NONE" command line argument was given. -6. Load the plugin scripts. *load-plugins* +7. Load the plugin scripts. *load-plugins* This does the same as the command: > :runtime! plugin/**/*.vim < The result is that all directories in the 'runtimepath' option will be @@ -503,26 +504,26 @@ accordingly. Vim proceeds in this order: if packages have been found, but that should not add a directory ending in "after". -7. Set 'shellpipe' and 'shellredir' +8. Set 'shellpipe' and 'shellredir' The 'shellpipe' and 'shellredir' options are set according to the value 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. -8. Set 'updatecount' to zero, if "-n" command argument used +9. Set 'updatecount' to zero, if "-n" command argument used -9. Set binary options +10. Set binary options If the "-b" flag was given to Vim, the options for binary editing will be set now. See |-b|. -10. Read the ShaDa file +11. Read the ShaDa file See |shada-file|. -11. Read the quickfix file +12. Read the quickfix file If the "-q" flag was given to Vim, the quickfix file is read. If this fails, Vim exits. -12. Open all windows +13. Open all windows When the |-o| flag was given, windows will be opened (but not displayed yet). When the |-p| flag was given, tab pages will be created (but not @@ -531,7 +532,7 @@ accordingly. Vim proceeds in this order: If the "-q" flag was given to Vim, the first error is jumped to. Buffers for all windows will be loaded. -13. Execute startup commands +14. Execute startup commands If a "-t" flag was given to Vim, the tag is jumped to. The commands given with the |-c| and |+cmd| arguments are executed. If the 'insertmode' option is set, Insert mode is entered. @@ -540,29 +541,6 @@ accordingly. Vim proceeds in this order: The |VimEnter| autocommands are executed. -Some hints on using initializations ~ - -Standard setup: -Create a vimrc file to set the default settings and mappings for all your edit -sessions. Put it in a place so that it will be found by 3b: - ~/.config/nvim/init.vim (Unix) - ~/AppData/Local/nvim/init.vim (Win32) - -Local setup: -Put all commands that you need for editing a specific directory only into a -vimrc file and place it in that directory under the name ".nvimrc" ("_nvimrc" -for Windows). NOTE: To make Vim look for these special files you -have to turn on the option 'exrc'. See |trojan-horse| too. - -System setup: -This only applies if you are managing a Unix system with several users and -want to set the defaults for all users. Create a vimrc file with commands -for default settings and mappings and put it in the place that is given with -the ":version" command. NOTE: System vimrc file needs specific compilation -options (one needs to define SYS_VIMRC_FILE macros). If :version command does -not show anything like this, consider contacting the nvim package maintainer. - - Saving the current state of Vim to a file ~ Whenever you have changed values of options or when you have created a @@ -570,20 +548,6 @@ mapping, then you may want to save them in a vimrc file for later use. See |save-settings| about saving the current state of settings to a file. -Avoiding setup problems for Vi users ~ - -Vi uses the variable EXINIT and the file "~/.exrc". So if you do not want to -interfere with Vi, then use the variable VIMINIT and the file init.vim -instead. - - -MS-DOS line separators: ~ - -On Windows systems Vim assumes that all the vimrc files have <CR> <NL> pairs -as line separators. This will give problems if you have a file with only -<NL>s and have a line like ":map xx yy^M". The trailing ^M will be ignored. - - Avoiding trojan horses ~ *trojan-horse* While reading the "vimrc" or the "exrc" file in the current directory, some @@ -606,7 +570,7 @@ it possible for another user to create a nasty vimrc and make you the owner. Be careful! When using tag search commands, executing the search command (the last part of the line in the tags file) is always done in secure mode. This works -just like executing a command from a vimrc/exrc in the current directory. +just like executing a command from a vimrc in the current directory. If Vim startup is slow ~ @@ -620,27 +584,29 @@ moment (use the Vim argument "-i NONE", |-i|). Try reducing the number of lines stored in a register with ":set shada='20,<50,s10". |shada-file|. -Intro message ~ - *:intro* -When Vim starts without a file name, an introductory message is displayed (for -those who don't know what Vim is). It is removed as soon as the display is -redrawn in any way. To see the message again, use the ":intro" command (if -there is not enough room, you will see only part of it). - To avoid the intro message on startup, add the 'I' flag to 'shortmess'. +Troubleshooting broken configurations ~ + *bisect* +The extreme flexibility of editors like Vim and Emacs means that any plugin or +setting can affect the entire editor in ways that are not initially obvious. - *info-message* -The |--help| and |--version| arguments cause Nvim to print a message and then -exit. Normally the message is sent to stdout, thus can be redirected to a -file with: > +To find the cause of a problem in your config, you must "bisect" it: +1. Remove or disable half of your `init.vim`. +2. Restart Nvim. +3. If the problem still occurs, goto 1. +4. If the problem is gone, restore half of the removed lines. +5. Continue narrowing your config in this way, until you find the setting or + plugin causing the issue. - nvim --help >file -From inside Nvim: > - - :read !nvim --help +Intro message ~ + *:intro* +When Vim starts without a file name, an introductory message is displayed. It +is removed as soon as the display is redrawn. To see the message again, use +the ":intro" command. To avoid the intro message on startup, add the "I" flag +to 'shortmess'. ============================================================================== -3. $VIM and $VIMRUNTIME +$VIM and $VIMRUNTIME *$VIM* The environment variable "$VIM" is used to locate various user files for Nvim, such as the user startup script |init.vim|. This depends on the system, see @@ -683,9 +649,9 @@ greps in the help files) you might be able to use this: > VIMRUNTIME="$(nvim --clean --headless --cmd 'echo $VIMRUNTIME|q')" ============================================================================== -4. Suspending *suspend* +Suspending *suspend* - *iconize* *iconise* *CTRL-Z* *v_CTRL-Z* + *CTRL-Z* *v_CTRL-Z* CTRL-Z Suspend Nvim, like ":stop". Works in Normal and in Visual mode. In Insert and Command-line mode, the CTRL-Z is inserted as a normal @@ -706,7 +672,7 @@ CTRL-Z Suspend Nvim, like ":stop". In the GUI, suspending is implementation-defined. ============================================================================== -5. Exiting *exiting* +Exiting *exiting* There are several ways to exit Vim: - Close the last window with `:quit`. Only when there are no changes. @@ -719,7 +685,7 @@ When using `:cquit` or when there was an error message Vim exits with exit code 1. Errors can be avoided by using `:silent!` or with `:catch`. ============================================================================== -6. Saving settings *save-settings* +Saving settings *save-settings* Mostly you will edit your vimrc files manually. This gives you the greatest flexibility. There are a few commands to generate a vimrc file automatically. @@ -776,7 +742,7 @@ these steps: You need to escape special characters, esp. spaces. ============================================================================== -7. Views and Sessions *views-sessions* +Views and Sessions *views-sessions* This is introduced in sections |21.4| and |21.5| of the user manual. @@ -920,7 +886,7 @@ To automatically save and restore views for *.c files: > au BufWinEnter *.c silent! loadview ============================================================================== -8. The ShaDa file *shada* *shada-file* +Shada ("shared data") file *shada* *shada-file* If you exit Vim and later start it again, you would normally lose a lot of information. The ShaDa file can be used to remember that information, which @@ -1358,7 +1324,7 @@ file when reading and include: complete MessagePack object. ============================================================================== -9. Standard Paths *standard-path* +Standard Paths *standard-path* Nvim stores configuration and data in standard locations. Plugins are strongly encouraged to follow this pattern also. Use |stdpath()| to get the paths. @@ -1389,4 +1355,5 @@ debugging, plugins and RPC clients. > Usually the file is ~/.local/share/nvim/log unless that path is inaccessible or if $NVIM_LOG_FILE was set before |startup|. + vim:noet:tw=78:ts=8:ft=help:norl: |