starting.txt (67844B)
1 *starting.txt* Nvim 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7 Starting Vim *starting* 8 9 Type |gO| to see the table of contents. 10 11 ============================================================================== 12 Nvim arguments *cli-arguments* 13 14 Most often, Nvim is started to edit a single file with the command: > 15 16 nvim filename 17 18 More generally, Nvim is started with: > 19 20 nvim [option | filename] .. 21 22 Option arguments and file name arguments can be mixed, and any number of them 23 can be given. However, watch out for options that take an argument. 24 25 The following items decide how to start editing: 26 27 *-file* *---* 28 filename One or more file names. The first one will be the current 29 file and read into the buffer. The cursor will be positioned 30 on the first line of the buffer. 31 To avoid a file name starting with a '-' being interpreted as 32 an option, precede the arglist with "--", e.g.: > 33 nvim -- -filename 34 < All arguments after "--" are interpreted as file names, no 35 other options or "+command" arguments can follow. 36 37 *--* 38 `-` Alias for stdin (standard input). 39 Example: > 40 echo text | nvim - file 41 < "text" is read into buffer 1, "file" is opened as buffer 2. 42 In most cases (except -s, -es, |--embed|, --headless) if stdin 43 is not a TTY then it is read as text, so "-" is implied: > 44 echo text | nvim file 45 < The buffer will be marked as modified, because it contains 46 text that needs to be saved (except for readonly |-R| mode). 47 If you don't like that, put these lines in your init.vim: > 48 " Don't set 'modified' when reading from stdin 49 au StdinReadPost * set nomodified 50 < 51 To read stdin as Normal commands use |-s| with "-": > 52 echo "ifoo" | nvim -s - 53 < To read stdin as Ex commands use |-es| or |-e|: > 54 echo "echo getpid()" | nvim -e - -V1 55 < To open a file literally named "-", put it after "--": > 56 echo foo | nvim -- - 57 < To read stdin as text with |--headless| use "-". 58 59 *-t* *-tag* 60 -t {tag} A tag. "tag" is looked up in the tags file, the associated 61 file becomes the current file, and the associated command is 62 executed. Mostly this is used for C programs, in which case 63 "tag" often is a function name. The effect is that the file 64 containing that function becomes the current file and the 65 cursor is positioned on the start of the function (see 66 |tags|). 67 68 *-q* *-qf* 69 -q [errorfile] QuickFix mode. The file with the name [errorfile] is read 70 and the first error is displayed. See |quickfix|. 71 If [errorfile] is not given, the 'errorfile' option is used 72 for the file name. See 'errorfile' for the default value. 73 74 (nothing) Without one of the four items above, Vim will start editing a 75 new buffer. It's empty and doesn't have a file name. 76 77 *startup-options* 78 The option arguments may be given in any order. Single-letter options can be 79 combined after one dash. There can be no option arguments after the "--" 80 argument. 81 82 --help *-h* *--help* *-?* 83 -? 84 -h Give usage (help) message and exit. 85 86 --version *-v* *--version* 87 -v Print version information and exit. Same output as for 88 |:version| command. 89 90 *--clean* 91 --clean Mimics a fresh install of Nvim: 92 - Skips initializations from files and environment variables. 93 - No 'shada' file is read or written. 94 - Excludes user directories from 'runtimepath' 95 - Loads builtin plugins, unlike "-u NONE -i NONE". 96 97 *--noplugin* 98 --noplugin Skip loading plugins. Resets the 'loadplugins' option. 99 Note that the |-u| argument may also disable loading plugins: 100 argument load vimrc files load plugins ~ 101 (nothing) yes yes 102 -u NONE no no 103 -u NORC no yes 104 --noplugin yes no 105 106 --startuptime {fname} *--startuptime* 107 During startup write timing messages to the file {fname}. 108 This can be used to find out where time is spent while loading 109 your |config|, plugins and opening the first file. 110 When {fname} already exists new messages are appended. 111 112 *-+* 113 +[num] The cursor will be positioned on line "num" for the first 114 file being edited. If "num" is missing, the cursor will be 115 positioned on the last line. 116 117 *-+/* 118 +/{pat} The cursor will be positioned on the first line containing 119 "pat" in the first file being edited (see |pattern| for the 120 available search patterns). The search starts at the cursor 121 position, which can be the first line or the cursor position 122 last used from |shada|. To force a search from the first 123 line use "+1 +/pat". 124 125 +{command} *-+c* *-c* 126 -c {command} {command} will be executed after the first file has been 127 read (and after autocommands and modelines for that file have 128 been processed). "command" is interpreted as an Ex command. 129 If the "command" contains spaces, it must be enclosed in 130 double quotes (this depends on the shell that is used). 131 Example: > 132 vim "+set si" main.c 133 vim "+find stdio.h" 134 vim -c "set ff=dos" -c wq mine.mak 135 < 136 Note: You can use up to 10 "+" or "-c" arguments in a Vim 137 command. They are executed in the order given. A "-S" 138 argument counts as a "-c" argument as well. 139 140 --cmd {command} *--cmd* 141 {command} will be executed before processing any vimrc file. 142 Otherwise, it acts like -c {command}. You can use up to 10 of 143 these commands, independently from "-c" commands. 144 145 *-S* 146 -S [file] Executes Vimscript or Lua (".lua") [file] after the first file 147 has been read. See also |:source|. If [file] is not given, 148 defaults to "Session.vim". Equivalent to: > 149 -c "source {file}" 150 < Can be repeated like "-c", subject to the same limit of 10 151 "-c" arguments. {file} cannot start with a "-". 152 153 -L *-L* *-r* 154 -r Recovery mode. Without a file name argument, a list of 155 existing swap files is given. With a file name, a swap file 156 is read to recover a crashed editing session. See 157 |crash-recovery|. 158 159 *-R* 160 -R Readonly mode. The 'readonly' option will be set for all the 161 files being edited. You can still edit the buffer, but will 162 be prevented from accidentally overwriting a file. If you 163 forgot that you are in View mode and did make some changes, 164 you can overwrite a file by adding an exclamation mark to 165 the Ex command, as in ":w!". The 'readonly' option can be 166 reset with ":set noro" (see the options chapter, |options|). 167 Subsequent edits will not be done in readonly mode. 168 The 'updatecount' option will be set to 10000, meaning that 169 the swap file will not be updated automatically very often. 170 See |-M| for disallowing modifications. 171 172 *-m* 173 -m Modifications not allowed to be written. The 'write' option 174 will be reset, so that writing files is disabled. However, 175 the 'write' option can be set to enable writing again. 176 177 *-M* 178 -M Modifications not allowed. The 'modifiable' option will be 179 reset, so that changes are not allowed. The 'write' option 180 will be reset, so that writing files is disabled. However, 181 the 'modifiable' and 'write' options can be set to enable 182 changes and writing. 183 184 -e *-e* *-E* 185 -E Start Nvim in Ex mode |gQ|, see |Ex-mode|. 186 187 If stdin is not a TTY: 188 -e reads/executes stdin as Ex commands. 189 -E reads stdin as text (into buffer 1). 190 191 -es *-es* *-Es* *-s-ex* *silent-mode* 192 -Es Script mode, aka "silent mode", aka "batch mode". No UI, 193 disables most prompts and messages. Unrelated to |-s|. 194 See also |-S| to run script files. 195 196 -es reads/executes stdin as Ex commands. > 197 printf "put ='foo'\n%%print\n" | nvim -es 198 199 < -Es reads stdin as text (into buffer 1). Use |-c| or "+" to 200 send commands. > 201 printf "foo\n" | nvim -Es +"%print" 202 203 < These commands display on stdout: 204 :list 205 :number 206 :print 207 :set 208 With |:verbose| or 'verbose', other commands display on stderr: > 209 nvim -es +"verbose echo 'foo'" 210 nvim -V1 -es +"echo 'foo'" 211 < 212 Skips user |config| unless |-u| was given. 213 Disables |shada| unless |-i| was given. 214 Disables swapfile (like |-n|). 215 216 *-l* 217 -l {script} [args] 218 Executes Lua {script} non-interactively (no UI) with optional 219 [args] after processing any preceding Nvim |cli-arguments|, 220 then exits. Exits 1 on Lua error. See |-S| to run multiple Lua 221 scripts without args, with a UI. 222 *lua-args* 223 All [args] are treated as {script} arguments and stored in the 224 Lua `_G.arg` global table, thus "-l" ends processing of Nvim 225 arguments. The {script} name is stored at `_G.arg[0]`. 226 227 Sets 'verbose' to 1 (like "-V1"), so Lua `print()` writes to 228 output, as well as other message-emitting functions like 229 |:echo|. 230 If {script} prints messages and doesn't cause Nvim to exit, 231 Nvim ensures output ends with a newline. 232 233 Arguments before "-l" are processed before executing {script}. 234 This example quits before executing "foo.lua": > 235 nvim +q -l foo.lua 236 < This loads Lua module "bar" before executing "foo.lua": > 237 nvim +"lua require('bar')" -l foo.lua 238 < *lua-shebang* 239 You can set the "shebang" of the script so that Nvim executes 240 the script when called with "./" from a shell (remember to 241 "chmod u+x"): > 242 #!/usr/bin/env -S nvim -l 243 < 244 Skips user |config| unless |-u| was given. 245 Disables plugins unless 'loadplugins' was set. 246 Disables |shada| unless |-i| was given. 247 Disables swapfile (like |-n|). 248 249 *-ll* 250 -ll {script} [args] 251 Executes a Lua script, similarly to |-l|, but the editor is not 252 initialized. This gives a Lua environment similar to a worker 253 thread. See |lua-loop-threading|. 254 255 Unlike `-l` no prior arguments are allowed. 256 257 *-b* 258 -b Binary mode. File I/O will only recognize <NL> to separate 259 lines. The 'expandtab' option will be reset. The 'textwidth' 260 option is set to 0. 'modeline' is reset. The 'binary' option 261 is set. This is done after reading the |vimrc| but before 262 reading any file in the arglist. See also |edit-binary|. 263 264 *-A* 265 -A Arabic mode. Sets the 'arabic' option on. 266 267 *-H* 268 -H Hebrew mode. Sets the 'rightleft' option on and the 'keymap' 269 option to "hebrew". 270 271 *-V* *verbose* 272 -V[N] Verbose. Sets the 'verbose' option to [N] (default: 10). 273 Messages will be given for each file that is ":source"d and 274 for reading or writing a ShaDa file. Can be used to find 275 out what is happening upon startup and exit. 276 Example: > 277 nvim -V8 278 279 -V[N]{file} 280 Like -V and sets 'verbosefile' to {file} (must not start with 281 a digit). Messages are not displayed, instead they are 282 written to {file}. 283 Example: > 284 nvim -V20vimlog 285 < 286 *-D* 287 -D Debugging. Go to debugging mode when executing the first 288 command from a script. |debug-mode| 289 290 *-n* 291 -n Disables |swap-file| by setting 'updatecount' to 0 (after 292 executing any |vimrc|). Recovery after a crash will be 293 impossible. Improves performance when working with a file on 294 a very slow medium (usb drive, network share). 295 296 Enable it again by setting 'updatecount' to some value, e.g. 297 ":set updatecount=100". 298 299 To reduce accesses to the disk, don't use "-n", but set 300 'updatetime' and 'updatecount' to very big numbers, and type 301 ":preserve" when you want to save your work. This way you 302 keep the possibility for crash recovery. 303 304 *-o* 305 -o[N] Open N windows, split horizontally. If [N] is not given, 306 one window is opened for every file given as argument. If 307 there is not enough room, only the first few files get a 308 window. If there are more windows than arguments, the last 309 few windows will be editing an empty file. 310 311 *-O* 312 -O[N] Open N windows, split vertically. Otherwise, it's like -o. 313 If both the -o and the -O option are given, the last one on 314 the command line determines how the windows will be split. 315 316 *-p* 317 -p[N] Open N tab pages. If [N] is not given, one tab page is opened 318 for every file given as argument. The maximum is set with 319 'tabpagemax' pages (default 50). If there are more tab pages 320 than arguments, the last few tab pages will be editing an 321 empty file. Also see |tabpage|. 322 *-d* 323 -d Start in |diff-mode|. 324 325 *-u* *E282* 326 -u {vimrc} The file {vimrc} is read for initializations. Most other 327 initializations are skipped; see |initialization|. 328 329 This can be used to start Vim in a special mode, with special 330 mappings and settings. A shell alias can be used to make 331 this easy to use. For example, in a C shell descendant: > 332 alias vimc 'nvim -u ~/.config/nvim/c_init.vim \!*' 333 < And in a Bash shell: > 334 alias vimc='nvim -u ~/.config/nvim/c_init.vim' 335 < Also consider using autocommands; see |autocommand|. 336 337 When {vimrc} is "NONE" (all uppercase), all initializations 338 from files and environment variables are skipped. Plugins and 339 syntax highlighting are also skipped. 340 341 When {vimrc} is "NORC" (all uppercase), this has the same 342 effect as "NONE", but plugins and syntax highlighting are not 343 skipped. 344 345 *-i* 346 -i {shada} The file {shada} is used instead of the default ShaDa 347 file. If the name "NONE" is used (all uppercase), no ShaDa 348 file is read or written, even if 'shada' is set or when 349 ":rsh" or ":wsh" are used. See also |shada-file|. 350 351 *-s* 352 -s {scriptin} Read script file {scriptin}, interpreting characters as 353 Normal-mode input. The same can be done with ":source!": > 354 :source! {scriptin} 355 < Reads from stdin if {scriptin} is "-": > 356 echo "ifoo" | nvim -s - 357 < If the end of the file is reached before Nvim exits, further 358 characters are read from the keyboard. 359 360 Does not work with |-es|. See also |complex-repeat|. 361 362 *-w_nr* 363 -w {number} 364 -w{number} Set the 'window' option to {number}. 365 366 *-w* 367 -w {scriptout} All keys that you type are recorded in the file "scriptout", 368 until you exit Vim. Useful to create a script file to be used 369 with "vim -s" or ":source!". Appends to the "scriptout" file 370 if it already exists. {scriptout} cannot start with a digit. 371 See also |vim.on_key()|. 372 See also |complex-repeat|. 373 374 *-W* 375 -W {scriptout} Like -w, but do not append, overwrite an existing file. 376 377 *--api-info* 378 --api-info Print msgpack-encoded |api-metadata| and exit. 379 380 *--embed* 381 --embed Use stdin/stdout as a msgpack-RPC channel, so applications can 382 embed and control Nvim via the RPC |API|. If the channel is 383 closed (except by |:detach|), Nvim exits. 384 385 Waits for the client ("embedder") to call |nvim_ui_attach()| 386 before sourcing startup files and reading buffers, so that UIs 387 can deterministically handle (display) early messages, 388 dialogs, etc. The client can do other requests before 389 `nvim_ui_attach` (e.g. `nvim_get_api_info` for feature-detection). 390 During this pre-startup phase the user config is of course not 391 available (similar to `--cmd`). 392 393 Non-UI embedders must pass |--headless|, then startup will 394 continue without waiting for `nvim_ui_attach`: > 395 nvim --embed --headless 396 < which is equivalent to: > 397 nvim --headless --cmd "call stdioopen({'rpc': v:true})" 398 < 399 UI embedders that want the UI protocol on a socket (instead of 400 stdio) must pass |--listen| as well as |--embed|: > 401 nvim --embed --listen addr 402 403 < See also: |ui-startup| |channel-stdio| 404 405 *--headless* 406 --headless Start without UI, and do not wait for `nvim_ui_attach`. The 407 builtin TUI is not used, so stdio works as an arbitrary 408 communication channel. |channel-stdio| 409 410 Also useful for scripting (tests) to see messages that would 411 not be printed by |-es|. 412 413 To detect if a UI is available, check if |nvim_list_uis()| is 414 empty during or after |VimEnter|. 415 416 To read stdin as text, "-" must be given explicitly: 417 --headless cannot assume that stdin is just text. > 418 echo foo | nvim --headless +"%print" +"q!" - 419 < 420 See also |--embed|. 421 See also |-es|, which also disables most messages. 422 423 --listen {addr} *--listen* 424 Start |RPC| server on pipe or TCP address {addr}. Sets the 425 primary listen address |v:servername| to {addr}. |serverstart()| 426 427 To start the server on-demand with systemd, use a systemd 428 socket unit and associated service unit running: > 429 systemd-socket-proxyd --exit-idle-time 430 < 431 ============================================================================== 432 Initialization *initialization* *startup* 433 434 At startup, Nvim checks environment variables and files and sets values 435 accordingly, proceeding as follows: 436 437 1. Set the 'shell' option *SHELL* *COMSPEC* 438 The environment variable SHELL, if it exists, is used to set the 439 'shell' option. On Win32, the COMSPEC variable is used 440 if SHELL is not set. 441 442 2. Process the arguments 443 The options and file names from the command that start Vim are 444 inspected. 445 The |-V| argument can be used to display or log what happens next, 446 useful for debugging the initializations. 447 The |--cmd| arguments are executed. 448 Buffers are created for all files (but not loaded yet). 449 450 3. Start a server (unless |--listen| was given) and set |v:servername|. 451 452 4. Wait for UI to connect. 453 Nvim started with |--embed| waits for the UI to connect before 454 proceeding to load user configuration. 455 456 5. Setup |default-mappings| and |default-autocmds|. Create |popup-menu|. 457 458 6. Enable filetype and indent plugins. 459 This does the same as the command: > 460 :runtime! ftplugin.vim indent.vim 461 < Skipped if the "-u NONE" command line argument was given. 462 463 7. Load user config (execute Ex commands from files, environment, …). 464 $VIMINIT environment variable is read as one Ex command line (separate 465 multiple commands with '|' or <NL>). 466 *config* *init.vim* *init.lua* *vimrc* *exrc* 467 A file containing initialization commands is generically called 468 a "vimrc" or config file. It can be either Vimscript ("init.vim") or 469 Lua ("init.lua"), but not both. *E5422* 470 See also |vimrc-intro| and |base-directories|. 471 472 The config file is located at: 473 Unix ~/.config/nvim/init.vim (or init.lua) 474 Windows ~/AppData/Local/nvim/init.vim (or init.lua) 475 |$XDG_CONFIG_HOME| $XDG_CONFIG_HOME/nvim/init.vim (or init.lua) 476 477 If Nvim was started with "-u {file}" then {file} is used as the config 478 and all initializations until 8. are skipped. $MYVIMRC is not set. 479 "nvim -u NORC" can be used to skip these initializations without 480 reading a file. "nvim -u NONE" also skips plugins and syntax 481 highlighting. |-u| 482 483 If Nvim was started with |-es| or |-Es| or |-l| all initializations until 8. 484 are skipped. 485 *system-vimrc* *sysinit.vim* 486 a. The system vimrc file is read for initializations. If 487 nvim/sysinit.vim file exists in one of $XDG_CONFIG_DIRS, it will be 488 used. Otherwise the system vimrc file is used. The path of this file 489 is given by the |:version| command. Usually it's "$VIM/sysinit.vim". 490 491 *VIMINIT* *EXINIT* *$MYVIMRC* 492 b. Locations searched for initializations, in order of preference: 493 - $VIMINIT environment variable (Ex command line). 494 - User |config|: $XDG_CONFIG_HOME/nvim/init.vim (or init.lua). 495 - Other config: {dir}/nvim/init.vim (or init.lua) where {dir} is any 496 directory in $XDG_CONFIG_DIRS. 497 - $EXINIT environment variable (Ex command line). 498 |$MYVIMRC| is set to the first valid location unless it was already 499 set or when using $VIMINIT. 500 501 c. If the 'exrc' option is on (which is NOT the default), the current 502 directory is searched for the following files, in order of precedence: 503 - ".nvim.lua" 504 - ".nvimrc" 505 - ".exrc" 506 The first that exists is used, the others are ignored. 507 508 8. Enable filetype detection. 509 This does the same as the command: > 510 :runtime! filetype.lua 511 < Skipped if ":filetype off" was called or if the "-u NONE" command line 512 argument was given. 513 514 9. Enable syntax highlighting. 515 This does the same as the command: > 516 :runtime! syntax/syntax.vim 517 < Skipped if ":syntax off" was called or if the "-u NONE" command 518 line argument was given. 519 520 10. Set the |v:vim_did_init| variable to 1. 521 522 11. Load the plugin scripts. *load-plugins* 523 This does the same as the command: > 524 :runtime! plugin/**/*.{vim,lua} 525 < The result is that all directories in 'runtimepath' will be searched 526 for the "plugin" sub-directory and all files ending in ".vim" or 527 ".lua" will be sourced (in alphabetical order per directory), 528 also in subdirectories. First "*.vim" are sourced, then "*.lua" files, 529 per directory. 530 531 However, directories in 'runtimepath' ending in "after" are skipped 532 here and only loaded after packages, see below. 533 Loading plugins won't be done when: 534 - The 'loadplugins' option was reset in a vimrc file. 535 - The |--noplugin| command line argument is used. 536 - The |--clean| command line argument is used. 537 - The "-u NONE" command line argument is used |-u|. 538 Note that using `-c 'set noloadplugins'` doesn't work, because the 539 commands from the command line have not been executed yet. You can 540 use `--cmd 'set noloadplugins'` or `--cmd 'set loadplugins'` |--cmd|. 541 542 Packages are loaded. These are plugins, as above, but found in the 543 "start" directory of each entry in 'packpath'. Every plugin directory 544 found is added in 'runtimepath' and then the plugins are sourced. See 545 |packages|. 546 547 The plugins scripts are loaded, as above, but now only the directories 548 ending in "after" are used. Note that 'runtimepath' will have changed 549 if packages have been found, but that should not add a directory 550 ending in "after". 551 552 12. Set 'shellpipe' and 'shellredir' 553 The 'shellpipe' and 'shellredir' options are set according to the 554 value of the 'shell' option, unless they have been set before. 555 This means that Nvim will figure out the values of 'shellpipe' and 556 'shellredir' for you, unless you have set them yourself. 557 558 13. Set 'updatecount' to zero, if "-n" command argument used. 559 560 14. Set binary options if the |-b| flag was given. 561 562 15. Read the |shada-file|. 563 564 16. Read the quickfix file if the |-q| flag was given, or exit on failure. 565 566 17. Open all windows 567 When the |-o| flag was given, windows will be opened (but not 568 displayed yet). 569 When the |-p| flag was given, tab pages will be created (but not 570 displayed yet). 571 When switching screens, it happens now. Redrawing starts. 572 If the |-q| flag was given, the first error is jumped to. 573 Buffers for all windows will be loaded, without triggering |BufAdd| 574 autocommands. 575 576 18. Execute startup commands 577 If a |-t| flag was given, the tag is jumped to. 578 Commands given with |-c| and |+cmd| are executed. 579 The starting flag is reset, has("vim_starting") will now return zero. 580 The |v:vim_did_enter| variable is set to 1. 581 The |VimEnter| autocommands are executed. 582 583 584 Saving the current state of Vim to a file ~ 585 586 Whenever you have changed values of options or when you have created a 587 mapping, then you may want to save them in a vimrc file for later use. See 588 |save-settings| about saving the current state of settings to a file. 589 590 591 Avoiding trojan horses ~ 592 *trojan-horse* 593 While reading the "vimrc" or the "exrc" file in the current directory, some 594 commands can be disabled for security reasons by setting the 'secure' option. 595 This is always done when executing the command from a tags file. Otherwise, 596 it would be possible that you accidentally use a vimrc or tags file that 597 somebody else created and contains nasty commands. The disabled commands are 598 the ones that start a shell, the ones that write to a file, and ":autocmd". 599 The ":map" commands are echoed, so you can see which keys are being mapped. 600 If you want Vim to execute all commands in a local vimrc file, you 601 can reset the 'secure' option in the EXINIT or VIMINIT environment variable or 602 in the global exrc or vimrc file. This is not possible in vimrc or 603 exrc in the current directory, for obvious reasons. 604 On Unix systems, this only happens if you are not the owner of the 605 vimrc file. Warning: If you unpack an archive that contains a vimrc or exrc 606 file, it will be owned by you. You won't have the security protection. Check 607 the vimrc file before you start Vim in that directory, or reset the 'exrc' 608 option. Some Unix systems allow a user to do "chown" on a file. This makes 609 it possible for another user to create a nasty vimrc and make you the owner. 610 Be careful! 611 When using tag search commands, executing the search command (the last 612 part of the line in the tags file) is always done in secure mode. This works 613 just like executing a command from a vimrc in the current directory. 614 615 616 If Vim startup is slow ~ 617 *slow-start* 618 If Vim takes a long time to start up, use the |--startuptime| argument to find 619 out what happens. 620 621 If you have 'shada' enabled, the loading of the ShaDa file may take a 622 while. You can find out if this is the problem by disabling ShaDa for a 623 moment (use the Vim argument "-i NONE", |-i|). Try reducing the number of 624 lines stored in a register with ":set shada='20,<50,s10". |shada-file|. 625 626 627 Troubleshooting broken configurations ~ 628 *bisect* 629 The extreme flexibility of editors like Vim and Emacs means that any plugin or 630 setting can affect the entire editor in ways that are not initially obvious. 631 632 To find the cause of a problem in your config, you must "bisect" it: 633 1. Remove or disable half of your |config|. 634 2. Restart Nvim. 635 3. If the problem still occurs, goto 1. 636 4. If the problem is gone, restore half of the removed lines. 637 5. Continue narrowing your config in this way, until you find the setting or 638 plugin causing the issue. 639 640 641 Intro message ~ 642 *:intro* 643 When Vim starts without a file name, an introductory message is displayed. It 644 is removed as soon as the display is redrawn. To see the message again, use 645 the ":intro" command. To avoid the intro message on startup, add the "I" flag 646 to 'shortmess'. 647 648 ============================================================================== 649 $VIM and $VIMRUNTIME 650 *$VIM* 651 The environment variable "$VIM" is used to locate various user files for Nvim, 652 such as the user |config|. This depends on the system, see 653 |startup|. 654 655 Nvim will try to get the value for $VIM in this order: 656 657 1. Environment variable $VIM, if it is set. 658 2. Path derived from the 'helpfile' option, unless it contains some 659 environment variable too (default is "$VIMRUNTIME/doc/help.txt"). File 660 name ("help.txt", etc.) is removed. Trailing directory names are removed, 661 in this order: "doc", "runtime". 662 3. Path derived from the location of the `nvim` executable. 663 4. Compile-time defined installation directory (see output of ":version"). 664 665 After doing this once, Nvim sets the $VIM environment variable. 666 667 *$VIMRUNTIME* 668 The environment variable "$VIMRUNTIME" is used to locate various support 669 files, such as the documentation and syntax-highlighting files. For example, 670 the main help file is normally "$VIMRUNTIME/doc/help.txt". 671 672 Nvim will try to get the value for $VIMRUNTIME in this order: 673 674 1. Environment variable $VIMRUNTIME, if it is set. 675 2. Directory path "$VIM/runtime", if it exists. 676 3. Value of $VIM environment variable. This is for backwards compatibility 677 with older Vim versions. 678 4. If "../share/nvim/runtime" exists relative to |v:progpath|, it is used. 679 5. Path derived from the 'helpfile' option (if it doesn't contain '$') with 680 "doc/help.txt" removed from the end. 681 682 After doing this once, Nvim sets the $VIMRUNTIME environment variable. 683 684 In case you need the value of $VIMRUNTIME in a shell (e.g., for a script that 685 greps in the help files) you might be able to use this: > 686 687 VIMRUNTIME="$(nvim --clean --headless --cmd 'echo $VIMRUNTIME|q')" 688 689 ============================================================================== 690 Suspending *suspend* 691 692 *CTRL-Z* *v_CTRL-Z* 693 CTRL-Z Suspend Nvim, like ":stop". 694 Works in Normal and in Visual mode. In Insert and 695 Command-line mode, the CTRL-Z is inserted as a normal 696 character. In Visual mode Nvim goes back to Normal 697 mode before suspending. 698 699 :sus[pend][!] or *:sus* *:suspend* *:st* *:stop* 700 :st[op][!] Suspend Nvim using OS "job control"; it will continue 701 if you make it the foreground job again. Triggers 702 |VimSuspend| before suspending and |VimResume| when 703 resumed. 704 If "!" is not given and 'autowrite' is set, every 705 buffer with changes and a file name is written out. 706 If "!" is given or 'autowrite' is not set, changed 707 buffers are not written, don't forget to bring Nvim 708 back to the foreground later! 709 710 In the GUI, suspending is implementation-defined. 711 712 ============================================================================== 713 Exiting *exiting* 714 715 There are several ways to exit Vim: 716 - Close the last window with `:quit`. Only when there are no changes. 717 - Close the last window with `:quit!`. Also when there are changes. 718 - Close all windows with `:qall`. Only when there are no changes. 719 - Close all windows with `:qall!`. Also when there are changes. 720 - Use `:cquit`. Also when there are changes. 721 722 When using `:cquit` or when there was an error message Vim exits with exit 723 code 1. Errors can be avoided by using `:silent!` or with `:catch`. 724 725 ============================================================================== 726 Saving settings *save-settings* 727 728 Mostly you will edit your vimrc files manually. This gives you the greatest 729 flexibility. There are a few commands to generate a vimrc file automatically. 730 You can use these files as they are, or copy/paste lines to include in another 731 vimrc file. 732 733 *:mk* *:mkexrc* 734 :mk[exrc] [file] Write current key mappings and changed options to 735 [file] (default ".exrc" in the current directory), 736 unless it already exists. 737 738 :mk[exrc]! [file] Always write current key mappings and changed 739 options to [file] (default ".exrc" in the current 740 directory). 741 742 *:mkv* *:mkvi* *:mkvimrc* 743 :mkv[imrc][!] [file] Like ":mkexrc", but the default is ".nvimrc" in the 744 current directory. The ":version" command is also 745 written to the file. 746 747 These commands will write ":map" and ":set" commands to a file, in such a way 748 that when these commands are executed, the current key mappings and options 749 will be set to the same values. The options 'columns', 'endofline', 750 'fileformat', 'lines', 'modified', and 'scroll' are not included, because 751 these are terminal or file dependent. 752 Note that the options 'binary', 'paste' and 'readonly' are included, this 753 might not always be what you want. 754 755 When special keys are used in mappings, the 'cpoptions' option will be 756 temporarily set to its Vim default, to avoid the mappings to be 757 misinterpreted. This makes the file incompatible with Vi, but makes sure it 758 can be used with different terminals. 759 760 Only global mappings are stored, not mappings local to a buffer. 761 762 A common method is to use a default |config| file, make some modifications 763 with ":map" and ":set" commands and write the modified file. First read the 764 default vimrc in with a command like ":source ~piet/.vimrc.Cprogs", change 765 the settings and then save them in the current directory with ":mkvimrc!". If 766 you want to make this file your default |config|, move it to 767 $XDG_CONFIG_HOME/nvim. You could also use autocommands |autocommand| and/or 768 modelines |modeline|. 769 770 *vimrc-option-example* 771 If you only want to add a single option setting to your vimrc, you can use 772 these steps: 773 1. Edit your vimrc file with Vim. 774 2. Play with the option until it's right. E.g., try out different values for 775 'guifont'. 776 3. Append a line to set the value of the option, using the expression register 777 '=' to enter the value. E.g., for the 'guifont' option: > 778 o:set guifont=<C-R>=&guifont<CR><Esc> 779 < [<C-R> is a CTRL-R, <CR> is a return, <Esc> is the escape key] 780 You need to escape special characters, esp. spaces. 781 782 ============================================================================== 783 Views and Sessions *views-sessions* 784 785 This is introduced in sections |21.4| and |21.5| of the user manual. 786 787 *View* *view-file* 788 A View is a collection of settings that apply to one window. You can save a 789 View and when you restore it later, the text is displayed in the same way. 790 The options and mappings in this window will also be restored, so that you can 791 continue editing like when the View was saved. 792 793 *Session* *session-file* 794 A Session keeps the Views for all windows, plus the global settings. You can 795 save a Session and when you restore it later the window layout looks the same. 796 You can use a Session to quickly switch between different projects, 797 automatically loading the files you were last working on in that project. 798 799 Views and Sessions are a nice addition to ShaDa files, which are used to 800 remember information for all Views and Sessions together |shada-file|. 801 802 You can quickly start editing with a previously saved View or Session with the 803 |-S| argument: > 804 vim -S Session.vim 805 < 806 *:mks* *:mksession* 807 :mks[ession][!] [file] Write a Vim script that restores the current editing 808 session. 809 When [!] is included, an existing file is overwritten. 810 When [file] is omitted, "Session.vim" is used. 811 812 The output of ":mksession" is like ":mkvimrc", but additional commands are 813 added to the file. Which ones depends on the 'sessionoptions' option. The 814 resulting file, when executed with a ":source" command: 815 1. Restores global mappings and options, if 'sessionoptions' contains 816 "options". Script-local mappings will not be written. 817 2. Restores global variables that start with an uppercase letter and contain 818 at least one lowercase letter, if 'sessionoptions' contains "globals". 819 3. Closes all windows in the current tab page, except the current one; closes 820 all tab pages except the current one (this results in currently loaded 821 buffers to be unloaded, some may become hidden if 'hidden' is set or 822 otherwise specified); wipes out the current buffer, if it is empty and 823 unnamed. 824 4. Restores the current directory, if 'sessionoptions' contains "curdir", or 825 sets the current directory to where the Session file is, if 826 'sessionoptions' contains "sesdir". 827 5. Restores GUI Vim window position, if 'sessionoptions' contains "winpos". 828 6. Restores screen size, if 'sessionoptions' contains "resize". 829 7. Reloads the buffer list, with the last cursor positions. If 830 'sessionoptions' contains "buffers" then all buffers are restored, 831 including hidden and unloaded buffers. Otherwise, only buffers in windows 832 are restored. 833 8. Restores all windows with the same layout. If 'sessionoptions' contains 834 "help", help windows are restored. If 'sessionoptions' contains "blank", 835 windows editing a buffer without a name will be restored. 836 If 'sessionoptions' contains "winsize" and no (help/blank) windows were 837 left out, the window sizes are restored (relative to the screen size). 838 Otherwise, the windows are just given sensible sizes. 839 9. Restores the Views for all the windows, as with |:mkview|. But 840 'sessionoptions' is used instead of 'viewoptions'. 841 10. If a file exists with the same name as the Session file, but ending in 842 "x.vim" (for eXtra), executes that as well. You can use `*x.vim` files to 843 specify additional settings and actions associated with a given Session, 844 such as creating menu items in the GUI version. 845 846 After restoring the Session, the full filename of your current Session is 847 available in the internal variable |v:this_session|. 848 An example mapping: > 849 :nmap <F2> :wa<Bar>exe "mksession! " .. v:this_session<CR>:so ~/sessions/ 850 This saves the current Session, and starts off the command to load another. 851 852 A session includes all tab pages, unless "tabpages" was removed from 853 'sessionoptions'. |tab-page| 854 855 The |SessionLoadPre| autocmd event is triggered before a session file is 856 loaded/sourced and |SessionLoadPost| autocmd event is triggered after. 857 *SessionLoad-variable* 858 While the session file is loading, the SessionLoad global variable is set to 859 1. Plugins can use this to postpone some work until the SessionLoadPost event 860 is triggered. 861 862 *:mkvie* *:mkview* 863 :mkvie[w][!] [file] Write a Vim script that restores the contents of the 864 current window. 865 When [!] is included, an existing file is overwritten. 866 When [file] is omitted or is a number from 1 to 9, a 867 name is generated and 'viewdir' prepended. When the 868 last path part of 'viewdir' does not exist, this 869 directory is created. E.g., when 'viewdir' is 870 "$VIM/vimfiles/view" then "view" is created in 871 "$VIM/vimfiles". 872 An existing file is always overwritten then. Use 873 |:loadview| to load this view again. 874 When [file] is the name of a file ('viewdir' is not 875 used), a command to edit the file is added to the 876 generated file. 877 878 The output of ":mkview" contains these items: 879 1. The argument list used in the window. When the global argument list is 880 used, it is reset to the global list. 881 The index in the argument list is also restored. 882 2. The file being edited in the window. If there is no file, the window is 883 made empty. 884 3. Restore mappings, abbreviations and options local to the window, if 885 'viewoptions' contains "options" or "localoptions". Only option values 886 that are local to the current buffer and the current window are restored. 887 When storing the view as part of a session and "options" is in 888 'sessionoptions', global values for local options will be stored too. 889 4. Restore folds when using manual folding and 'viewoptions' contains 890 "folds". Restore manually opened and closed folds. 891 5. The scroll position and the cursor position in the file. Doesn't work very 892 well when there are closed folds. 893 6. The local current directory, if it is different from the global current 894 directory and 'viewoptions' contains "curdir". 895 896 Note that Views and Sessions are not perfect: 897 - They don't restore everything. For example, defined functions, autocommands 898 and ":syntax on" are not included. Things like register contents and 899 command line history are in ShaDa, not in Sessions or Views. 900 - Global option values are only set when they differ from the default value. 901 When the current value is not the default value, loading a Session will not 902 set it back to the default value. Local options will be set back to the 903 default value though. 904 - Existing mappings will be overwritten without warning. An existing mapping 905 may cause an error for ambiguity. 906 - When storing manual folds and when storing manually opened/closed folds, 907 changes in the file between saving and loading the view will mess it up. 908 - The Vim script is not very efficient. But still faster than typing the 909 commands yourself! 910 911 *:lo* *:loadview* 912 :lo[adview] [nr] Load the view for the current file. When [nr] is 913 omitted, the view stored with ":mkview" is loaded. 914 When [nr] is specified, the view stored with ":mkview 915 [nr]" is loaded. 916 917 The combination of ":mkview" and ":loadview" can be used to store up to ten 918 different views of a file. These are remembered in the directory specified 919 with the 'viewdir' option. The views are stored using the file name. If a 920 file is renamed or accessed through a (symbolic) link, the view will not be 921 found. 922 923 You might want to clean up your 'viewdir' directory now and then. 924 925 To automatically save and restore views for `*.c` files: > 926 au BufWinLeave *.c mkview 927 au BufWinEnter *.c silent! loadview 928 929 ============================================================================== 930 Shada ("shared data") file *shada* *shada-file* 931 932 If you exit Vim and later start it again, you would normally lose a lot of 933 information. The ShaDa file can be used to remember that information, which 934 enables you to continue where you left off. Its name is the abbreviation of 935 SHAred DAta because it is used for sharing data between Nvim sessions. 936 937 This is introduced in section |21.3| of the user manual. 938 939 The ShaDa file is used to store: 940 - The command line history. 941 - The search string history. 942 - The input-line history. 943 - Contents of non-empty registers. 944 - Marks for several files. 945 - File marks, pointing to locations in files. 946 - Last search/substitute pattern (for 'n' and '&'). 947 - The buffer list. 948 - Global variables. 949 950 You could also use a Session file. The difference is that the ShaDa file 951 does not depend on what you are working on. There normally is only one 952 ShaDa file. Session files are used to save the state of a specific editing 953 Session. You could have several Session files, one for each project you are 954 working on. ShaDa and Session files together can be used to effectively 955 enter Vim and directly start working in your desired setup. |session-file| 956 957 *shada-read* 958 When Vim is started and the 'shada' option is non-empty, the contents of 959 the ShaDa file are read and the info can be used in the appropriate places. 960 The |v:oldfiles| variable is filled. The marks are not read in at startup 961 (but file marks are). See |initialization| for how to set the 'shada' 962 option upon startup. 963 964 *shada-write* 965 When Vim exits and 'shada' is non-empty, the info is stored in the ShaDa file 966 (it's actually merged with the existing one, if one exists |shada-merging|). 967 The 'shada' option is a string containing information about what info should 968 be stored, and contains limits on how much should be stored (see 'shada'). 969 970 Notes for Unix: 971 - The file protection for the ShaDa file will be set to prevent other users 972 from being able to read it, because it may contain any text or commands that 973 you have worked with. 974 - If you want to share the ShaDa file with other users (e.g. when you "su" 975 to another user), you can make the file writable for the group or everybody. 976 Vim will preserve this when writing new ShaDa files. Be careful, don't 977 allow just anybody to read and write your ShaDa file! 978 - Vim will not overwrite a ShaDa file that is not writable by the current 979 "real" user. This helps for when you did "su" to become root, but your 980 $HOME is still set to a normal user's home directory. Otherwise, Vim would 981 create a ShaDa file owned by root that nobody else can read. 982 - The ShaDa file cannot be a symbolic link. This is to avoid security 983 issues. 984 985 Marks are stored for each file separately. When a file is read and 'shada' 986 is non-empty, the marks for that file are read from the ShaDa file. NOTE: 987 The marks are only written when exiting Vim, which is fine because marks are 988 remembered for all the files you have opened in the current editing session, 989 unless ":bdel" is used. If you want to save the marks for a file that you are 990 about to abandon with ":bdel", use ":wsh". The '[' and ']' marks are not 991 stored, but the '"' mark is. The '"' mark is very useful for jumping to the 992 cursor position when the file was last exited. No marks are saved for files 993 that start with any string given with the "r" flag in 'shada'. This can be 994 used to avoid saving marks for files on removable media (for MS-Windows you 995 would use "ra:,rb:"). 996 The |v:oldfiles| variable is filled with the file names that the ShaDa file 997 has marks for. 998 999 *shada-file-marks* 1000 Uppercase marks ('A to 'Z) are stored when writing the ShaDa file. The 1001 numbered marks ('0 to '9) are a bit special. When the ShaDa file is written 1002 (when exiting or with the |:wshada| command), '0 is set to the current 1003 cursor position and file. The old '0 is moved to '1, '1 to '2, etc. This 1004 resembles what happens with the "1 to "9 delete registers. If the current 1005 cursor position is already present in '0 to '9, it is moved to '0, to avoid 1006 having the same position twice. The result is that with "'0", you can jump 1007 back to the file and line where you exited Vim. To do that right away, try 1008 using this command: > 1009 1010 vim -c "normal '0" 1011 1012 In a C shell descendant, you could make an alias for it: > 1013 1014 alias lvim vim -c '"'normal "'"0'"' 1015 1016 For a Bash-like shell: > 1017 1018 alias lvim='vim -c "normal '\''0"' 1019 1020 Use the "r" flag in 'shada' to specify for which files no marks should be 1021 remembered. 1022 1023 MERGING *shada-merging* 1024 1025 When writing ShaDa files with |:wshada| without bang or at regular exit 1026 information in the existing ShaDa file is merged with information from current 1027 Nvim instance. For this purpose ShaDa files store timestamps associated 1028 with ShaDa entries. Specifically the following is being done: 1029 1030 1. History lines are merged, ordered by timestamp. Maximum amount of items in 1031 ShaDa file is defined by 'shada' option (|shada-/|, |shada-:|, |shada-@|, 1032 etc: one suboption for each character that represents history name 1033 (|:history|)). 1034 2. Local marks and changes for files that were not opened by Nvim are copied 1035 to new ShaDa file. Marks for files that were opened by Nvim are merged, 1036 changes to files opened by Nvim are ignored. |shada-'| 1037 3. Jump list is merged: jumps are ordered by timestamp, identical jumps 1038 (identical position AND timestamp) are squashed. 1039 4. Search patterns and substitute strings are not merged: search pattern or 1040 substitute string which has greatest timestamp will be the only one copied 1041 to ShaDa file. 1042 5. For each register entity with greatest timestamp is the only saved. 1043 |shada-<| 1044 6. All saved variables are saved from current Nvim instance. Additionally 1045 existing variable values are copied, meaning that the only way to remove 1046 variable from a ShaDa file is either removing it by hand or disabling 1047 writing variables completely. |shada-!| 1048 7. For each global mark entity with greatest timestamp is the only saved. 1049 8. Buffer list and header are the only entries which are not merged in any 1050 fashion: the only header and buffer list present are the ones from the 1051 Nvim instance which was last writing the file. |shada-%| 1052 1053 COMPATIBILITY *shada-compatibility* 1054 1055 ShaDa files are forward and backward compatible. This means that 1056 1057 1. Entries which have unknown type (i.e. that hold unidentified data) are 1058 ignored when reading and blindly copied when writing. 1059 2. Register entries with unknown register name are ignored when reading and 1060 blindly copied when writing. Limitation: only registers that use name with 1061 code in interval [1, 255] are supported. |registers| 1062 3. Register entries with unknown register type are ignored when reading and 1063 merged as usual when writing. |getregtype()| 1064 4. Local and global mark entries with unknown mark names are ignored when 1065 reading. When writing global mark entries are blindly copied and local mark 1066 entries are also blindly copied, but only if file they are attached to fits 1067 in the |shada-'| limit. Unknown local mark entry's timestamp is also taken 1068 into account when calculating which files exactly should fit into this 1069 limit. Limitation: only marks that use name with code in interval [1, 255] 1070 are supported. |mark-motions| 1071 5. History entries with unknown history type are ignored when reading and 1072 blindly copied when writing. Limitation: there can be only up to 256 1073 history types. |history| 1074 6. Unknown keys found in register, local mark, global mark, change, jump and 1075 search pattern entries are saved internally and dumped when writing. 1076 Entries created during Nvim session never have such additions. 1077 7. Additional elements found in replacement string and history entries are 1078 saved internally and dumped. Entries created during Nvim session never 1079 have such additions. 1080 8. Additional elements found in variable entries are simply ignored when 1081 reading. When writing new variables they will be preserved during merging, 1082 but that's all. Variable values dumped from current Nvim session never 1083 have additional elements, even if variables themselves were obtained by 1084 reading ShaDa files. 1085 1086 "Blindly" here means that there will be no attempts to somehow merge them, 1087 even if other entries (with known name/type/etc) are merged. |shada-merging| 1088 1089 SHADA FILE NAME *shada-file-name* 1090 1091 - Default name of the |shada| file is: 1092 Unix: "$XDG_STATE_HOME/nvim/shada/main.shada" 1093 Windows: "$XDG_STATE_HOME/nvim-data/shada/main.shada" 1094 See also |base-directories|. 1095 - To choose a different file name you can use: 1096 - The "n" flag in the 'shada' option. 1097 - The |-i| startup argument. "NONE" means no shada file is ever read or 1098 written. Also not for the commands below! 1099 - The 'shadafile' option. The value from the "-i" argument (if any) is 1100 stored in the 'shadafile' option. 1101 - For the commands below, another file name can be given, overriding the 1102 default and the name given with 'shada' or "-i" (unless it's NONE). 1103 1104 1105 MANUALLY READING AND WRITING *shada-read-write* 1106 1107 Two commands can be used to read and write the ShaDa file manually. This 1108 can be used to exchange registers between two running Vim programs: First 1109 type ":wsh" in one and then ":rsh" in the other. Note that if the register 1110 already contained something, then ":rsh!" would be required. Also note, 1111 however, that this means everything will be overwritten with information from 1112 the first Vim, including the command line history, etc. 1113 1114 The ShaDa file itself can be edited by hand too, although we suggest you 1115 start with an existing one to get the format right. You need to understand 1116 MessagePack (or, more likely, find software that is able to use it) format to 1117 do this. This can be useful in order to create a second file, say 1118 "~/.my.shada", which could contain certain settings that you always want when 1119 you first start Nvim. For example, you can preload registers with 1120 particular data, or put certain commands in the command line history. A line 1121 in your |config| file like > 1122 :rshada! ~/.my.shada 1123 can be used to load this information. You could even have different ShaDa 1124 files for different types of files (e.g., C code) and load them based on the 1125 file name, using the ":autocmd" command (see |:autocmd|). More information on 1126 ShaDa file format is contained in |shada-format| section. 1127 1128 *E136* *E929* *shada-error-handling* 1129 Some errors make Nvim leave temporary file named `{basename}.tmp.X` (X is 1130 any free letter from `a` to `z`) while normally it will create this file, 1131 write to it and then rename `{basename}.tmp.X` to `{basename}`. Such errors 1132 include: 1133 1134 - Errors which make Nvim think that the file being read is not a ShaDa 1135 file at all: 1136 non-ShaDa files are not overwritten for safety reasons to avoid accidentally 1137 destroying an unrelated file. This could happen e.g. when typing "nvim -i 1138 file" in place of "nvim -R file" (yes, somebody did that at least with Vim). 1139 Such errors are listed at |shada-critical-contents-errors|. 1140 - If writing to the temporary file failed: e.g. because of the insufficient 1141 space left. 1142 - If renaming file failed: e.g. because of insufficient permissions. 1143 - If target ShaDa file has different from the Nvim instance's owners (user 1144 and group) and changing them failed. Unix-specific, applies only when 1145 Nvim was launched from root. 1146 1147 Do not forget to remove the temporary file or replace the target file with 1148 temporary one after getting one of the above errors or all attempts to create 1149 a ShaDa file may fail with |E929|. If you got one of them when using 1150 |:wshada| (and not when exiting Nvim: i.e. when you have Nvim session 1151 running) you have additional options: 1152 1153 - First thing which you should consider if you got any error, except failure 1154 to write to the temporary file: remove existing file and replace it with the 1155 temporary file. Do it even if you have running Nvim instance. 1156 - Fix the permissions and/or file ownership, free some space and attempt to 1157 write again. Do not remove the existing file. 1158 - Use |:wshada| with bang. Does not help in case of permission error. If 1159 target file was actually the ShaDa file some information may be lost in this 1160 case. To make the matters slightly better use |:rshada| prior to writing, 1161 but this still will loose buffer-local marks and change list entries for any 1162 file which is not opened in the current Nvim instance. 1163 - Remove the target file from shell and use |:wshada|. Consequences are not 1164 different from using |:wshada| with bang, but "rm -f" works in some cases 1165 when you don't have write permissions. 1166 1167 *:rsh* *:rshada* *E886* 1168 :rsh[ada][!] [file] Read from ShaDa file [file] (default: see above). 1169 If [!] is given, then any information that is 1170 already set (registers, marks, |v:oldfiles|, etc.) 1171 will be overwritten. 1172 1173 *:wsh* *:wshada* *E137* 1174 :wsh[ada][!] [file] Write to ShaDa file [file] (default: see above). 1175 The information in the file is first read in to make 1176 a merge between old and new info. When [!] is used, 1177 the old information is not read first, only the 1178 internal info is written (also disables safety checks 1179 described in |shada-error-handling|). If 'shada' is 1180 empty, marks for up to 100 files will be written. 1181 When you get error "E929: All .tmp.X files exist, 1182 cannot write ShaDa file!", check that no old temp 1183 files were left behind (e.g. 1184 ~/.local/state/nvim/shada/main.shada.tmp*). 1185 1186 Note: Executing :wshada will reset all |'quote| marks. 1187 1188 *:o* *:ol* *:oldfiles* 1189 :o[ldfiles] List the files that have marks stored in the ShaDa 1190 file. This list is read on startup and only changes 1191 afterwards with `:rshada!`. Also see |v:oldfiles|. 1192 The number can be used with |c_#<|. 1193 The output can be filtered with |:filter|, e.g.: > 1194 filter /\.vim/ oldfiles 1195 < The filtering happens on the file name. 1196 1197 :bro[wse] o[ldfiles][!] 1198 List file names as with |:oldfiles|, and then prompt 1199 for a number. When the number is valid that file from 1200 the list is edited. 1201 If you get the |press-enter| prompt you can press "q" 1202 and still get the prompt to enter a file number. 1203 Use [!] to abandon a modified buffer. |abandon| 1204 1205 SHADA FILE FORMAT *shada-format* 1206 1207 ShaDa files are concats of MessagePack entries. Each entry is a concat of 1208 exactly four MessagePack objects: 1209 1210 1. First goes type of the entry. Object type must be an unsigned integer. 1211 Object type must not be equal to zero. 1212 2. Second goes entry timestamp. It must also be an unsigned integer. 1213 3. Third goes the length of the fourth entry. Unsigned integer as well, used 1214 for fast skipping without parsing. 1215 4. Fourth is actual entry data. All currently used ShaDa entries use 1216 containers to hold data: either map or array. All string values in those 1217 containers are either binary (applies to filenames) or UTF-8, yet parser 1218 needs to expect that invalid bytes may be present in a UTF-8 string. 1219 1220 Exact format depends on the entry type: 1221 1222 Entry type (name) Entry data ~ 1223 1 (Header) Map containing data that describes the generator 1224 instance that wrote this ShaDa file. It is ignored 1225 when reading ShaDa files. Contains the following data: 1226 Key Data ~ 1227 generator Binary, software used to generate ShaDa 1228 file. Is equal to "nvim" when ShaDa file was 1229 written by Nvim. 1230 version Binary, generator version. 1231 encoding Binary, effective 'encoding' value. 1232 max_kbyte Integer, effective |shada-s| limit value. 1233 pid Integer, instance process ID. 1234 `*` It is allowed to have any number of 1235 additional keys with any data. 1236 2 (SearchPattern) Map containing data describing last used search or 1237 substitute pattern. Normally ShaDa file contains two 1238 such entries: one with "ss" key set to true (describes 1239 substitute pattern, see |:substitute|), and one set to 1240 false (describes search pattern, see 1241 |search-commands|). "su" key should be true on one of 1242 the entries. If key value is equal to default then it 1243 is normally not present. Keys: 1244 Key Type Default Description ~ 1245 sm Boolean true Effective 'magic' value. 1246 sc Boolean false Effective 'smartcase' value. 1247 sl Boolean true True if search pattern comes 1248 with a line offset. See 1249 |search-offset|. 1250 se Boolean false True if |search-offset| 1251 requested to place cursor at 1252 (relative to) the end of the 1253 pattern. 1254 so Integer 0 Offset value. |search-offset| 1255 su Boolean false True if current entry was the 1256 last used search pattern. 1257 ss Boolean false True if current entry describes 1258 |:substitute| pattern. 1259 sh Boolean false True if |v:hlsearch| is on. 1260 With |shada-h| or 'nohlsearch' 1261 this key is always false. 1262 sp Binary N/A Actual pattern. Required. 1263 sb Boolean false True if search direction is 1264 backward. 1265 `*` any none Other keys are allowed for 1266 compatibility reasons, see 1267 |shada-compatibility|. 1268 3 (SubString) Array containing last |:substitute| replacement string. 1269 Contains single entry: binary, replacement string used. 1270 More entries are allowed for compatibility reasons, see 1271 |shada-compatibility|. 1272 4 (HistoryEntry) Array containing one entry from history. Should have 1273 two or three entries. First one is history type 1274 (unsigned integer), second is history line (binary), 1275 third is the separator character (unsigned integer, 1276 must be in interval [0, 255]). Third item is only 1277 valid for search history. Possible history types are 1278 listed in |hist-names|, here are the corresponding 1279 numbers: 0 - cmd, 1 - search, 2 - expr, 3 - input, 1280 4 - debug. 1281 5 (Register) Map describing one register (|registers|). If key 1282 value is equal to default then it is normally not 1283 present. Keys: 1284 Key Type Def Description ~ 1285 rt UInteger 0 Register type: 1286 No Description ~ 1287 0 |charwise-register| 1288 1 |linewise-register| 1289 2 |blockwise-register| 1290 rw UInteger 0 Register width. Only valid 1291 for |blockwise-register|s. 1292 rc Array of binary N/A Register contents. Each 1293 entry in the array 1294 represents its own line. 1295 NUL characters inside the 1296 line should be represented 1297 as NL according to 1298 |NL-used-for-Nul|. 1299 ru Boolean false Unnamed register. Whether 1300 the unnamed register had 1301 pointed to this register. 1302 n UInteger N/A Register name: character 1303 code in range [1, 255]. 1304 Example: |quote0| register 1305 has name 48 (ASCII code for 1306 zero character). 1307 * any none Other keys are allowed 1308 for compatibility reasons, 1309 see |shada-compatibility|. 1310 6 (Variable) Array containing two items: variable name (binary) and 1311 variable value (any object). Values are converted 1312 using the same code |msgpackparse()| uses when reading, 1313 |msgpackdump()| when writing, so there may appear 1314 |msgpack-special-dict|s. If there are more then two 1315 entries then the rest are ignored 1316 (|shada-compatibility|). 1317 7 (GlobalMark) 1318 8 (Jump) 1319 10 (LocalMark) 1320 11 (Change) Map containing some position description: 1321 Entry Position ~ 1322 GlobalMark Global mark position. |'A| 1323 LocalMark Local mark position. |'a| 1324 Jump One position from the |jumplist|. 1325 Change One position from the |changelist|. 1326 1327 Data contained in the map: 1328 Key Type Default Description ~ 1329 l UInteger 1 Position line number. Must be 1330 greater then zero. 1331 c UInteger 0 Position column number. 1332 n UInteger 34 ('"') Mark name. Only valid for 1333 GlobalMark and LocalMark 1334 entries. 1335 f Binary N/A File name. Required. 1336 `*` any none Other keys are allowed for 1337 compatibility reasons, see 1338 |shada-compatibility|. 1339 9 (BufferList) Array containing maps. Each map in the array 1340 represents one buffer. Possible keys: 1341 Key Type Default Description ~ 1342 l UInteger 1 Position line number. Must be 1343 greater then zero. 1344 c UInteger 0 Position column number. 1345 f Binary N/A File name. Required. 1346 `*` any none Other keys are allowed for 1347 compatibility reasons, see 1348 |shada-compatibility|. 1349 `*` (Unknown) Any other entry type is allowed for compatibility 1350 reasons, see |shada-compatibility|. 1351 1352 *E575* *E576* 1353 Errors in ShaDa file may have two types: 1354 1. E575 for “logical” errors. 1355 2. E576 for “critical” errors. 1356 When writing, critical errors trigger behaviour described in 1357 |shada-error-handling|. 1358 When reading, critical errors cause the rest of the file to be skipped. 1359 Critical errors include: 1360 *shada-critical-contents-errors* 1361 - Any of first three MessagePack objects being not an unsigned integer. 1362 - Third object requesting amount of bytes greater then bytes left in the ShaDa 1363 file. 1364 - Entry with zero type. I.e. first object being equal to zero. 1365 - MessagePack parser failing to parse the entry data. 1366 - MessagePack parser consuming less or requesting greater bytes then described 1367 in the third object for parsing fourth object. I.e. when fourth object 1368 either contains more then one MessagePack object or it does not contain 1369 complete MessagePack object. 1370 1371 ============================================================================== 1372 Standard Paths *standard-path* 1373 1374 Nvim stores configuration, data, and logs in standard locations. Plugins are 1375 strongly encouraged to follow this pattern also. Use |stdpath()| to get the 1376 paths. 1377 1378 *base-directories* *xdg* 1379 The "base" (root) directories conform to the XDG Base Directory Specification. 1380 https://specifications.freedesktop.org/basedir/latest/ 1381 The $XDG_CONFIG_HOME, $XDG_DATA_HOME, $XDG_RUNTIME_DIR, $XDG_STATE_HOME, 1382 $XDG_CACHE_HOME, $XDG_CONFIG_DIRS and $XDG_DATA_DIRS environment variables 1383 are used if defined, else default values (listed below) are used. 1384 1385 Note: In the help these defaults are used as placeholders, e.g. "~/.config" is 1386 understood as "$XDG_CONFIG_HOME or ~/.config". 1387 1388 CONFIG DIRECTORY (DEFAULT) ~ 1389 *$XDG_CONFIG_HOME* Nvim: stdpath("config") 1390 Unix: ~/.config ~/.config/nvim 1391 Windows: ~/AppData/Local ~/AppData/Local/nvim 1392 1393 DATA DIRECTORY (DEFAULT) ~ 1394 *$XDG_DATA_HOME* Nvim: stdpath("data") 1395 Unix: ~/.local/share ~/.local/share/nvim 1396 Windows: ~/AppData/Local ~/AppData/Local/nvim-data 1397 1398 RUN DIRECTORY (DEFAULT) ~ 1399 *$XDG_RUNTIME_DIR* Nvim: stdpath("run") 1400 Unix: /tmp/nvim.user/xxx /tmp/nvim.user/xxx 1401 Windows: $TMP/nvim.user/xxx $TMP/nvim.user/xxx 1402 1403 STATE DIRECTORY (DEFAULT) ~ 1404 *$XDG_STATE_HOME* Nvim: stdpath("state") 1405 Unix: ~/.local/state ~/.local/state/nvim 1406 Windows: ~/AppData/Local ~/AppData/Local/nvim-data 1407 1408 CACHE DIRECTORY (DEFAULT) ~ 1409 *$XDG_CACHE_HOME* Nvim: stdpath("cache") 1410 Unix: ~/.cache ~/.cache/nvim 1411 Windows: ~/AppData/Local/Temp ~/AppData/Local/Temp/nvim-data 1412 1413 LOG FILE (DEFAULT) ~ 1414 `$NVIM_LOG_FILE` Nvim: stdpath("log")/nvim.log 1415 Unix: ~/.local/state/nvim ~/.local/state/nvim/nvim.log 1416 Windows: ~/AppData/Local/nvim-data ~/AppData/Local/nvim-data/nvim.log 1417 1418 Note that stdpath("log") is currently an alias for stdpath("state"). 1419 1420 ADDITIONAL CONFIGS DIRECTORY (DEFAULT) ~ 1421 *$XDG_CONFIG_DIRS* Nvim: stdpath("config_dirs") 1422 Unix: /etc/xdg/ /etc/xdg/nvim 1423 Windows: Not applicable Not applicable 1424 1425 ADDITIONAL DATA DIRECTORY (DEFAULT) ~ 1426 *$XDG_DATA_DIRS* Nvim: stdpath("data_dirs") 1427 Unix: /usr/local/share /usr/local/share/nvim 1428 /usr/share /usr/share/nvim 1429 Windows: Not applicable Not applicable 1430 1431 NVIM_APPNAME *$NVIM_APPNAME* 1432 The standard directories can be further configured by the `$NVIM_APPNAME` 1433 environment variable. This variable controls the sub-directory that Nvim will 1434 read from (and auto-create) in each of the base directories. For example, 1435 setting `$NVIM_APPNAME` to "foo" before starting will cause Nvim to look for 1436 configuration files in `$XDG_CONFIG_HOME/foo` instead of 1437 `$XDG_CONFIG_HOME/nvim`. `$NVIM_APPNAME` must be a name, such as "foo", or a 1438 relative path, such as "foo/bar". 1439 1440 Note: In the help wherever `$XDG_CONFIG_…/nvim` is mentioned it is understood 1441 as `$XDG_CONFIG_…/$NVIM_APPNAME`. 1442 1443 *state-isolation* 1444 One use-case for $NVIM_APPNAME is to "isolate" Nvim applications. 1445 Alternatively, for true isolation, on Linux you can use cgroups namespaces: > 1446 systemd-run --user -qt -p PrivateUsers=yes -p BindPaths=/home/user/profile_xy:/home/user/.config/nvim nvim 1447 < 1448 *stateless* 1449 To run Nvim without creating any directories or data files: > 1450 NVIM_LOG_FILE=/dev/null nvim -n -i NONE 1451 1452 LOG FILE *log* *$NVIM_LOG_FILE* *E5430* 1453 Besides 'debug' and 'verbose', Nvim keeps a general log file for internal 1454 debugging, plugins and RPC clients. > 1455 :echo $NVIM_LOG_FILE 1456 Default location is stdpath("log")/log ($XDG_STATE_HOME/nvim/nvim.log) unless 1457 that path is inaccessible or $NVIM_LOG_FILE was set before |startup|. 1458 1459 1460 vim:noet:tw=78:ts=8:ft=help:norl: