diff options
Diffstat (limited to 'runtime/doc/starting.txt')
| -rw-r--r-- | runtime/doc/starting.txt | 280 |
1 files changed, 138 insertions, 142 deletions
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index 2c024d3c75..9b33926d04 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -1,4 +1,4 @@ -*starting.txt* For Vim version 7.4. Last change: 2016 Jul 03 +*starting.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -6,15 +6,7 @@ Starting Vim *starting* -1. Vim arguments |vim-arguments| -2. Initialization |initialization| -3. $VIM and $VIMRUNTIME |$VIM| -4. Suspending |suspend| -5. Exiting |exiting| -6. Saving settings |save-settings| -7. Views and Sessions |views-sessions| -8. The ShaDa file |shada-file| -9. Base Directories |base-directories| + Type |gO| to see the table of contents. ============================================================================== 1. Vim arguments *vim-arguments* @@ -61,7 +53,7 @@ filename One or more file names. The first one will be the current < Starting in Ex mode: > nvim -e - nvim -E -< Start editing in silent mode. See |-s-ex|. +< Start editing in |silent-mode|. *-t* *-tag* -t {tag} A tag. "tag" is looked up in the tags file, the associated @@ -181,6 +173,7 @@ argument. the executable "view" has the same effect as the -R argument. The 'updatecount' option will be set to 10000, meaning that the swap file will not be updated automatically very often. + See |-M| for disallowing modifications. *-m* -m Modifications not allowed to be written. The 'write' option @@ -207,7 +200,7 @@ argument. *-E* -E Start Vim in improved Ex mode |gQ|. - *-s-ex* + *-s-ex* *silent-mode* -s Silent or batch mode. Only when "-s" is preceded by the "-e" argument. Otherwise see |-s|, which does take an argument while this use of "-s" doesn't. To be used when Vim is used @@ -221,14 +214,14 @@ argument. :set to display option values. When 'verbose' is non-zero messages are printed (for debugging, to stderr). - $TERM is not used. + |$TERM| is not used. If Vim appears to be stuck try typing "qa!<Enter>". You don't get a prompt thus you can't see Vim is waiting for you to type something. Initializations are skipped (except the ones given with the "-u" argument). Example: > - vim -e -s < thefilter thefile + vim -es < thefilter thefile < *-b* -b Binary mode. File I/O will only recognize <NL> to separate @@ -356,13 +349,19 @@ argument. *--api-info* --api-info Print msgpack-encoded |api-metadata| and exit. + *--headless* +--headless Do not start the built-in UI. + See |channel-stdio| for how to use stdio for other purposes + instead. + See also |silent-mode|, which does start a (limited) UI. + ============================================================================== 2. Initialization *initialization* *startup* At startup, Vim checks environment variables and files and sets values accordingly. Vim proceeds in this order: -1. Set the 'shell' option *SHELL* *COMSPEC* *TERM* +1. Set the 'shell' option *SHELL* *COMSPEC* The environment variable SHELL, if it exists, is used to set the 'shell' option. On Windows, the COMSPEC variable is used if SHELL is not set. @@ -425,7 +424,7 @@ accordingly. Vim proceeds in this order: - The environment variable EXINIT. The value of $EXINIT is used as an Ex command line. - c. If the 'exrc' option is on (which is not the default), the current + c. If the 'exrc' option is on (which is NOT the default), the current directory is searched for three files. The first that exists is used, the others are ignored. - The file ".nvimrc" (for Unix) @@ -457,6 +456,8 @@ accordingly. Vim proceeds in this order: searched for the "plugin" sub-directory and all files ending in ".vim" will be sourced (in alphabetical order per directory), also in subdirectories. + However, directories in 'runtimepath' ending in "after" are skipped + here and only loaded after packages, see below. Loading plugins won't be done when: - The 'loadplugins' option was reset in a vimrc file. - The |--noplugin| command line argument is used. @@ -464,13 +465,18 @@ accordingly. Vim proceeds in this order: - When Vim was compiled without the |+eval| feature. Note that using "-c 'set noloadplugins'" doesn't work, because the commands from the command line have not been executed yet. You can - use "--cmd 'set noloadplugins'" |--cmd|. + use "--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'. Every plugin directory found is added in 'runtimepath' and then the plugins are sourced. See |packages|. + The plugins scripts are loaded, as above, but now only the directories + ending in "after" are used. Note that 'runtimepath' will have changed + if packages have been found, but that should not add a directory + ending in "after". + 7. 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. @@ -511,7 +517,8 @@ accordingly. Vim proceeds in this order: The |v:vim_did_enter| variable is set to 1. The |VimEnter| autocommands are executed. -Some hints on using initializations: + +Some hints on using initializations ~ Standard setup: Create a vimrc file to set the default settings and mappings for all your edit @@ -533,17 +540,23 @@ 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: + +Saving the current state of Vim to a file ~ + Whenever you have changed values of options or when you have created a 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: + +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: + +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. @@ -551,8 +564,10 @@ as line separators. This will give problems if you have a file with only The $MYVIMRC or $MYGVIMRC file will be set to the first found vimrc and/or gvimrc file. -Avoiding trojan horses: *trojan-horse* -While reading the vimrc or the exrc file in the current directory, some + +Avoiding trojan horses ~ + *trojan-horse* +While reading the "vimrc" or the "exrc" file in the current directory, some commands can be disabled for security reasons by setting the 'secure' option. This is always done when executing the command from a tags file. Otherwise it would be possible that you accidentally use a vimrc or tags file that somebody @@ -574,6 +589,8 @@ Be careful! 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. + +If Vim startup is slow ~ *slow-start* If Vim takes a long time to start up, use the |--startuptime| argument to find out what happens. @@ -583,6 +600,8 @@ while. You can find out if this is the problem by disabling ShaDa for a 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 @@ -616,54 +635,40 @@ though. ============================================================================== 3. $VIM and $VIMRUNTIME *$VIM* -The environment variable "$VIM" is used to locate various user files for 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 |startup|. -To avoid the need for every user to set the $VIM environment variable, Vim -will 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 in a specific directory for its support files. Example: > - setenv VIM /home/paul/vim -2. The path from 'helpfile' is used, unless it contains some environment - variable too (the default is "$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., "vim54"). -3. For MSDOS and Win32 Vim tries to use the directory name of the - executable. If it ends in "/src", this is removed. This is 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., "vim54"). -4. For Unix the compile-time defined installation directory is used (see the - output of ":version"). - -Once Vim has done this once, it will set the $VIM environment variable. To -change it later, use a ":let" command like this: > - :let $VIM = "/home/paul/vim/" -< +Nvim will try to get the value for $VIM in this order: + +1. Environment variable $VIM, if it is set. +2. Path derived from the 'helpfile' option, unless it contains some + environment variable too (default is "$VIMRUNTIME/doc/help.txt"). File + name ("help.txt", etc.) is removed. Trailing directory names are removed, + in this order: "doc", "runtime". +3. Path derived from the location of the `nvim` executable. +4. Compile-time defined installation directory (see output of ":version"). + +After doing this once, Nvim sets the $VIM environment variable. + *$VIMRUNTIME* The environment variable "$VIMRUNTIME" is used to locate various support -files, such as the on-line documentation and files used for syntax -highlighting. For example, the main help file is normally -"$VIMRUNTIME/doc/help.txt". -You don't normally set $VIMRUNTIME yourself, but let Vim figure it out. This -is the order used to find the value of $VIMRUNTIME: -1. If the environment variable $VIMRUNTIME is set, it is used. You can use - this when the runtime files are in an unusual location. -2. If "$VIM/vim{version}" exists, it is used. {version} is the version - number of Vim, without any '-' or '.'. For example: "$VIM/vim54". This is - the normal value for $VIMRUNTIME. -3. If "$VIM/runtime" exists, it is used. -4. The value of $VIM is used. This is for backwards compatibility with older - versions. +files, such as the documentation and syntax-highlighting files. For example, +the main help file is normally "$VIMRUNTIME/doc/help.txt". + +Nvim will try to get the value for $VIMRUNTIME in this order: + +1. Environment variable $VIMRUNTIME, if it is set. +2. Directory path "$VIM/vim{version}", if it exists, where {version} is the + Vim version number without '-' or '.'. For example: "$VIM/vim54". +3. Directory path "$VIM/runtime", if it exists. +4. Value of $VIM environment variable. This is for backwards compatibility + with older Vim versions. 5. If "../share/nvim/runtime" exists relative to |v:progpath|, it is used. -6. When the 'helpfile' option is set and doesn't contain a '$', its value is - used, with "doc/help.txt" removed from the end. +6. Path derived from the 'helpfile' option (if it doesn't contain '$') with + "doc/help.txt" removed from the end. -Once Vim has done this once, it will set the $VIMRUNTIME environment variable. -To change it later, use a ":let" command like this: > - :let $VIMRUNTIME = "/home/piet/vim/vim54" +After doing this once, Nvim sets the $VIMRUNTIME environment variable. In case you need the value of $VIMRUNTIME in a shell (e.g., for a script that greps in the help files) you might be able to use this: > @@ -714,7 +719,7 @@ There are several ways to exit Vim: - Use `:cquit`. Also when there are changes. When using `:cquit` or when there was an error message Vim exits with exit -code 1. Errors can be avoided by using `:silent!`. +code 1. Errors can be avoided by using `:silent!` or with `:catch`. ============================================================================== 6. Saving settings *save-settings* @@ -882,7 +887,7 @@ The output of ":mkview" contains these items: 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, if it is different from the global current - directory. + directory and 'viewoptions' contains "curdir". Note that Views and Sessions are not perfect: - They don't restore everything. For example, defined functions, autocommands @@ -915,7 +920,7 @@ You might want to clean up your 'viewdir' directory now and then. To automatically save and restore views for *.c files: > au BufWinLeave *.c mkview - au BufWinEnter *.c silent loadview + au BufWinEnter *.c silent! loadview ============================================================================== 8. The ShaDa file *shada* *shada-file* @@ -1090,23 +1095,6 @@ SHADA FILE NAME *shada-file-name* default and the name given with 'shada' or "-i" (unless it's NONE). -CHARACTER ENCODING *shada-encoding* - -The text in the ShaDa file is UTF-8-encoded. Normally you will always work -with the same 'encoding' value, and this works just fine. However, if you -read the ShaDa file with value for 'encoding' different from utf-8 and -'encoding' used when writing ShaDa file, some of the text (non-ASCII -characters) may be invalid as Neovim always attempts to convert the text in -the ShaDa file from the UTF-8 to the current 'encoding' value. Filenames are -never converted, affected elements are: - -- history strings; -- variable values; -- register values; -- last used search and substitute patterns; -- last used substitute replacement string. - - MANUALLY READING AND WRITING *shada-read-write* Two commands can be used to read and write the ShaDa file manually. This @@ -1192,8 +1180,11 @@ running) you have additional options: *:o* *:ol* *:oldfiles* :o[ldfiles] List the files that have marks stored in the ShaDa file. This list is read on startup and only changes - afterwards with ":rshada!". Also see |v:oldfiles|. + afterwards with `:rshada!`. Also see |v:oldfiles|. The number can be used with |c_#<|. + The output can be filtered with |:filter|, e.g.: > + filter /\.vim/ oldfiles +< The filtering happens on the file name. :bro[wse] o[ldfiles][!] List file names as with |:oldfiles|, and then prompt @@ -1214,8 +1205,11 @@ exactly four MessagePack objects: 3. Third goes the length of the fourth entry. Unsigned integer as well, used for fast skipping without parsing. 4. Fourth is actual entry data. All currently used ShaDa entries use - containers to hold data: either map or array. Exact format depends on the - entry type: + containers to hold data: either map or array. All string values in those + containers are either binary (applies to filenames) or UTF-8, yet parser + needs to expect that invalid bytes may be present in a UTF-8 string. + + Exact format depends on the entry type: Entry type (name) Entry data ~ 1 (Header) Map containing data that describes the generator @@ -1279,29 +1273,32 @@ exactly four MessagePack objects: 5 (Register) Map describing one register (|registers|). If key value is equal to default then it is normally not present. Keys: - Key Type Def Description ~ - rt UInteger 0 Register type: - No Description ~ - 0 |characterwise-register| - 1 |linewise-register| - 2 |blockwise-register| - rw UInteger 0 Register width. Only valid - for |blockwise-register|s. - rc Array of binary N/A Register contents. Each - entry in the array - represents its own line. - NUL characters inside the - line should be represented - as NL according to - |NL-used-for-Nul|. - n UInteger N/A Register name: character - code in range [1, 255]. - Example: |quote0| register - has name 48 (ASCII code for - zero character). - * any none Other keys are allowed - for compatibility reasons, - see |shada-compatibility|. + Key Type Def Description ~ + rt UInteger 0 Register type: + No Description ~ + 0 |characterwise-register| + 1 |linewise-register| + 2 |blockwise-register| + rw UInteger 0 Register width. Only valid + for |blockwise-register|s. + rc Array of binary N/A Register contents. Each + entry in the array + represents its own line. + NUL characters inside the + line should be represented + as NL according to + |NL-used-for-Nul|. + ru Boolean false Unnamed register. Whether + the unnamed register had + pointed to this register. + n UInteger N/A Register name: character + code in range [1, 255]. + Example: |quote0| register + has name 48 (ASCII code for + zero character). + * any none Other keys are allowed + for compatibility reasons, + see |shada-compatibility|. 6 (Variable) Array containing two items: variable name (binary) and variable value (any object). Values are converted using the same code |msgpackparse()| uses when reading, @@ -1361,39 +1358,38 @@ file when reading and include: complete MessagePack object. ============================================================================== -9. Base Directories *base-directories* *xdg* - -Nvim conforms to the XDG Base Directory Specification for application -configuration and data file locations. This just means Nvim looks for some -optional settings and uses them if they exist, otherwise defaults are chosen. -https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html - -CONFIGURATION DIRECTORY *$XDG_CONFIG_HOME* - - Base directory default: - Unix: ~/.config - Windows: ~/AppData/Local - - Nvim directory: - Unix: ~/.config/nvim/ - Windows: ~/AppData/Local/nvim/ +9. Standard Paths -DATA DIRECTORY *$XDG_DATA_HOME* +Nvim stores configuration and data in standard locations. Plugins are strongly +encouraged to follow this pattern also. - Base directory default: - Unix: ~/.local/share - Windows: ~/AppData/Local - - Nvim directory: - Unix: ~/.local/share/nvim/ - Windows: ~/AppData/Local/nvim-data/ - -Note on Windows the configuration and data directory defaults are the same -(for lack of an alternative), but the sub-directory for data is named -"nvim-data" to separate it from the configuration sub-directory "nvim". - -Throughout other sections of the user manual, the defaults are used as generic -placeholders, e.g. where "~/.config" is mentioned it should be understood to -mean "$XDG_CONFIG_HOME or ~/.config". + *base-directories* *xdg* +The "base" (root) directories conform to the XDG Base Directory Specification. +https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html +The $XDG_CONFIG_HOME and $XDG_DATA_HOME environment variables are used if they +exist, otherwise default values (listed below) are used. + +Note: Throughout the user manual these defaults are used as placeholders, e.g. +"~/.config" is understood to mean "$XDG_CONFIG_HOME or ~/.config". + +CONFIG DIRECTORY *$XDG_CONFIG_HOME* + Base Nvim ~ +Unix: ~/.config ~/.config/nvim +Windows: ~/AppData/Local ~/AppData/Local/nvim + +DATA DIRECTORY *$XDG_DATA_HOME* + Base Nvim ~ +Unix: ~/.local/share ~/.local/share/nvim +Windows: ~/AppData/Local ~/AppData/Local/nvim-data + +STANDARD PATHS *standard-path* + + *$NVIM_LOG_FILE* +Besides 'debug' and 'verbose', Nvim has a low-level "log of last resort" that +is written directly to the filesystem. This log may also be used by plugins or +RPC clients for debugging. $NVIM_LOG_FILE contains the log file path: > + :echo $NVIM_LOG_FILE +Usually the file is ~/.local/share/nvim/log unless that path is inaccessible +or if $NVIM_LOG_FILE was set before |startup|. vim:tw=78:ts=8:ft=help:norl: |