repeat.txt (59278B)
1 *repeat.txt* For Vim version 9.2. Last change: 2026 Oct 13 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7 Repeating commands, Vim scripts and debugging *repeating* 8 9 Chapter 26 of the user manual introduces repeating |usr_26.txt|. 10 11 1. Single repeats |single-repeat| 12 2. Multiple repeats |multi-repeat| 13 3. Complex repeats |complex-repeat| 14 4. Using Vim scripts |using-scripts| 15 5. Using Vim packages |packages| 16 6. Creating Vim packages |package-create| 17 7. Debugging scripts |debug-scripts| 18 8. Profiling |profiling| 19 20 ============================================================================== 21 1. Single repeats *single-repeat* 22 23 *.* 24 . Repeat last change, with count replaced with [count]. 25 Also repeat a yank command, when the 'y' flag is 26 included in 'cpoptions'. Does not repeat a 27 command-line command. 28 29 Simple changes can be repeated with the "." command. Without a count, the 30 count of the last change is used. If you enter a count, it will replace the 31 last one. |v:count| and |v:count1| will be set. 32 33 If the last change included a specification of a numbered register, the 34 register number will be incremented. See |redo-register| for an example how 35 to use this. 36 37 Note that when repeating a command that used a Visual selection, the same SIZE 38 of area is used, see |visual-repeat|. 39 40 *@:* 41 @: Repeat last command-line [count] times. 42 {not available when compiled without the 43 |+cmdline_hist| feature} 44 45 46 ============================================================================== 47 2. Multiple repeats *multi-repeat* 48 49 *:g* *:global* *E148* 50 :[range]g[lobal]/{pattern}/[cmd] 51 Execute the Ex command [cmd] (default ":p") on the 52 lines within [range] where {pattern} matches. 53 54 :[range]g[lobal]!/{pattern}/[cmd] 55 Execute the Ex command [cmd] (default ":p") on the 56 lines within [range] where {pattern} does NOT match. 57 58 *:v* *:vglobal* 59 :[range]v[global]/{pattern}/[cmd] 60 Same as :g!. 61 62 Example: > 63 :g/^Obsolete/d _ 64 Using the underscore after `:d` avoids clobbering registers or the clipboard. 65 This also makes it faster. 66 67 Instead of the '/' which surrounds the {pattern}, you can use any other 68 single byte character, but not an alphabetic character, '\', '"', '|' or '!'. 69 This is useful if you want to include a '/' in the search pattern or 70 replacement string. The closing delimiter is optional when [cmd] is not 71 given, and the pattern then terminates at <EOL>. 72 73 For the definition of a pattern, see |pattern|. 74 75 The default [cmd] is `:print`. 76 77 NOTE [cmd] may contain a range; see |collapse| and |edit-paragraph-join| for 78 examples. 79 80 The global commands work by first scanning through the [range] lines and 81 marking each line where a match occurs (for a multi-line pattern, only the 82 start of the match matters). 83 In a second scan the [cmd] is executed for each marked line, as if the cursor 84 was in that line. For ":v" and ":g!" the command is executed for each not 85 marked line. If a line is deleted its mark disappears. 86 The default for [range] is the whole buffer (1,$). Use "CTRL-C" to interrupt 87 the command. If an error message is given for a line, the command for that 88 line is aborted and the global command continues with the next marked or 89 unmarked line. 90 *E147* 91 When the command is used recursively, it only works on one line. Giving a 92 range is then not allowed. This is useful to find all lines that match a 93 pattern and do not match another pattern: > 94 :g/found/v/notfound/{cmd} 95 This first finds all lines containing "found", but only executes {cmd} when 96 there is no match for "notfound". 97 98 Any Ex command can be used, see |ex-cmd-index|. To execute a Normal mode 99 command, you can use the `:normal` command: > 100 :g/pat/normal {commands} 101 Make sure that {commands} ends with a whole command, otherwise Vim will wait 102 for you to type the rest of the command for each match. The screen will not 103 have been updated, so you don't know what you are doing. See |:normal|. 104 105 The undo/redo command will undo/redo the whole global command at once. 106 The previous context mark will only be set once (with "''" you go back to 107 where the cursor was before the global command). 108 109 The global command sets both the last used search pattern and the last used 110 substitute pattern (this is vi compatible). This makes it easy to globally 111 replace a string: > 112 :g/pat/s//PAT/g 113 This replaces all occurrences of "pat" with "PAT". The same can be done with: > 114 :%s/pat/PAT/g 115 Which is two characters shorter! 116 117 When using "global" in Ex mode, a special case is using ":visual" as a 118 command. This will move to a matching line, go to Normal mode to let you 119 execute commands there until you use |Q| to return to Ex mode. This will be 120 repeated for each matching line. While doing this you cannot use ":global". 121 To abort this type CTRL-C twice. 122 123 ============================================================================== 124 3. Complex repeats *complex-repeat* 125 126 *q* *recording* 127 q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"} 128 (uppercase to append). The 'q' command is disabled 129 while executing a register, and it doesn't work inside 130 a mapping and |:normal|. 131 132 Note: If the register being used for recording is also 133 used for |y| and |p| the result is most likely not 134 what is expected, because the put will paste the 135 recorded macro and the yank will overwrite the 136 recorded macro. 137 138 Note: The recording happens while you type, replaying 139 the register happens as if the keys come from a 140 mapping. This matters, for example, for undo, which 141 only syncs when commands were typed. 142 143 q Stops recording. (Implementation note: The 'q' that 144 stops recording is not stored in the register, unless 145 it was the result of a mapping) 146 147 *@* 148 @{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} [count] 149 times. Note that register '%' (name of the current 150 file) and '#' (name of the alternate file) cannot be 151 used. 152 The register is executed like a mapping, that means 153 that the difference between 'wildchar' and 'wildcharm' 154 applies, and undo might not be synced in the same way. 155 For "@=" you are prompted to enter an expression. The 156 result of the expression is then executed. 157 See also |@:|. 158 159 *@@* *E748* 160 @@ Repeat the previous @{0-9a-z":*} [count] times. 161 162 *:@* 163 :[addr]@{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} as an 164 Ex command. First set cursor at line [addr] (default 165 is current line). When the last line in the register 166 does not have a <CR> it will be added automatically 167 when the 'e' flag is present in 'cpoptions'. 168 For ":@=" the last used expression is used. The 169 result of evaluating the expression is executed as an 170 Ex command. 171 Mappings are not recognized in these commands. 172 When the |line-continuation| character (\) is present 173 at the beginning of a line in a linewise register, 174 then it is combined with the previous line. This is 175 useful for yanking and executing parts of a Vim 176 script. 177 Future: Will execute the register for each line in the 178 address range. 179 180 :[addr]*{0-9a-z".=+} *:star-compatible* 181 When '*' is present in 'cpoptions' |cpo-star|, use 182 ":*" in the same way as ":@". This is NOT the default 183 when 'nocompatible' is used. When the '*' flag is not 184 present in 'cpoptions', ":*" is an alias for ":'<,'>", 185 select the Visual area |:star|. 186 187 *:@:* 188 :[addr]@: Repeat last command-line. First set cursor at line 189 [addr] (default is current line). 190 191 :[addr]@ *:@@* 192 :[addr]@@ Repeat the previous :@{register}. First set cursor at 193 line [addr] (default is current line). 194 195 ============================================================================== 196 4. Using Vim scripts *using-scripts* 197 198 For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. 199 200 *:so* *:source* *load-vim-script* 201 :so[urce] {file} Read Ex commands from {file}. These are commands that 202 start with a ":". 203 Triggers the |SourcePre| autocommand. 204 *:source-range* 205 :[range]so[urce] [++clear] 206 Read Ex commands from the [range] of lines in the 207 current buffer. When [range] is omitted read all 208 lines. 209 210 When sourcing commands from the current buffer, the 211 same script-ID |<SID>| is used even if the buffer is 212 sourced multiple times. If a buffer is sourced more 213 than once, then the functions in the buffer are 214 defined again. 215 216 To source a range of lines that doesn't start with the 217 |:vim9script| command in Vim9 script context, the 218 |:vim9cmd| modifier can be used. If you use a Visual 219 selection and type ":", the range in the form "'<,'>" 220 can come before it: > 221 :'<,'>vim9cmd source 222 < Otherwise the range goes after the modifier and must 223 have a colon prefixed, like all Vim9 ranges: > 224 :vim9cmd :5,9source 225 226 < When a range of lines in a buffer is sourced in the 227 Vim9 script context, the previously defined 228 script-local variables and functions are not cleared. 229 This works like the range started with the 230 ":vim9script noclear" command. The "++clear" argument 231 can be used to clear the script-local variables and 232 functions before sourcing the script. This works like 233 the range started with the `:vim9script` command 234 without the "noclear" argument. See |vim9-reload| for 235 more information. 236 Examples: > 237 :4,5source 238 :10,18source ++clear 239 240 < Implementation detail: When sourcing a [range] of 241 lines that falls inside a folded region, the range 242 will be adjusted to the start and end of the fold, 243 but only if a two line specifiers range was used. 244 245 *:source!* 246 :so[urce]! {file} Read Vim commands from {file}. These are commands 247 that are executed from Normal mode, like you type 248 them. 249 When used after |:global|, |:argdo|, |:windo|, 250 |:bufdo|, in a loop or when another command follows 251 the display won't be updated while executing the 252 commands. 253 Cannot be used in the |sandbox|. 254 255 *:ru* *:runtime* 256 :ru[ntime][!] [where] {file} .. 257 Read Ex commands from {file} in each directory given 258 by 'runtimepath' and/or 'packpath'. There is no error 259 for non-existing files. 260 261 Example: > 262 :runtime syntax/c.vim 263 264 < There can be multiple {file} arguments, separated by 265 spaces. Each {file} is searched for in the first 266 directory from 'runtimepath', then in the second 267 directory, etc. Use a backslash to include a space 268 inside {file} (although it's better not to use spaces 269 in file names, it causes trouble). 270 271 When [!] is included, all found files are sourced. 272 When it is not included only the first found file is 273 sourced. 274 275 When [where] is omitted only 'runtimepath' is used. 276 Other values: 277 START search under "start" in 'packpath' 278 OPT search under "opt" in 'packpath' 279 PACK search under "start" and "opt" in 280 'packpath' 281 ALL first use 'runtimepath', then search 282 under "start" and "opt" in 'packpath' 283 284 When {file} contains wildcards it is expanded to all 285 matching files. Example: > 286 :runtime! plugin/**/*.vim 287 < This is what Vim uses to load the plugin files when 288 starting up. This similar command: > 289 :runtime plugin/**/*.vim 290 < would source the first file only. 291 292 When 'verbose' is one or higher, there is a message 293 when no file could be found. 294 When 'verbose' is two or higher, there is a message 295 about each searched file. 296 297 *:pa* *:packadd* *E919* 298 :pa[ckadd][!] {name} Search for an optional plugin directory in 'packpath' 299 and source any plugin files found. The directory must 300 match: 301 pack/*/opt/{name} ~ 302 The directory is added to 'runtimepath' if it wasn't 303 there yet. 304 If the directory pack/*/opt/{name}/after exists it is 305 added at the end of 'runtimepath'. 306 307 If loading packages from "pack/*/start" was skipped, 308 then this directory is searched first: 309 pack/*/start/{name} ~ 310 311 Note that {name} is the directory name, not the name 312 of the .vim file. All the files matching the pattern 313 pack/*/opt/{name}/plugin/**/*.vim ~ 314 will be sourced. This allows for using subdirectories 315 below "plugin", just like with plugins in 316 'runtimepath'. 317 318 If the filetype detection was not enabled yet (this 319 is usually done with a `syntax enable` or `filetype on` 320 command in your .vimrc file), this will also look 321 for "{name}/ftdetect/*.vim" files. 322 323 When the optional ! is added no plugin files or 324 ftdetect scripts are loaded, only the matching 325 directories are added to 'runtimepath'. This is 326 useful in your .vimrc. The plugins will then be 327 loaded during initialization, see |load-plugins| (note 328 that the loading order will be reversed, because each 329 directory is inserted before others). 330 Note that for ftdetect scripts to be loaded 331 you will need to write `filetype plugin indent on` 332 AFTER all `packadd!` commands. 333 334 To programmatically decide if `!` is needed during 335 startup, check |v:vim_did_init|: use `!` if 0 (to not 336 duplicate |load-plugins| step), no `!` otherwise (to 337 force load plugin files as otherwise they won't be 338 loaded automatically). 339 340 Also see |pack-add|. 341 {only available when compiled with |+eval|} 342 343 *:packl* *:packloadall* 344 :packl[oadall][!] Load all packages in the "start" directory under each 345 entry in 'packpath'. 346 347 First all the directories found are added to 348 'runtimepath', then the plugins found in the 349 directories are sourced. This allows for a plugin to 350 depend on something of another plugin, e.g. an 351 "autoload" directory. See |packload-two-steps| for 352 how this can be useful. 353 354 This is normally done automatically during startup, 355 after loading your .vimrc file. With this command it 356 can be done earlier. 357 358 Packages will be loaded only once. Using 359 `:packloadall` a second time will have no effect. 360 When the optional ! is added this command will load 361 packages even when done before. 362 363 Note that when using `:packloadall` in the |vimrc| 364 file, the 'runtimepath' option is updated, and later 365 all plugins in 'runtimepath' will be loaded, which 366 means they are loaded again. Plugins are expected to 367 handle that. 368 369 An error only causes sourcing the script where it 370 happens to be aborted, further plugins will be loaded. 371 See |packages|. 372 {only available when compiled with |+eval|} 373 374 :scripte[ncoding] [encoding] *:scripte* *:scriptencoding* *E167* 375 Specify the character encoding used in the script. 376 The following lines will be converted from [encoding] 377 to the value of the 'encoding' option, if they are 378 different. Examples: > 379 scriptencoding iso-8859-5 380 scriptencoding cp932 381 < 382 When [encoding] is empty, no conversion is done. This 383 can be used to restrict conversion to a sequence of 384 lines: > 385 scriptencoding euc-jp 386 ... lines to be converted ... 387 scriptencoding 388 ... not converted ... 389 390 < When conversion isn't supported by the system, there 391 is no error message and no conversion is done. When a 392 line can't be converted there is no error and the 393 original line is kept. 394 395 Don't use "ucs-2" or "ucs-4", scripts cannot be in 396 these encodings (they would contain NUL bytes). 397 When a sourced script starts with a BOM (Byte Order 398 Mark) in utf-8 format Vim will recognize it, no need 399 to use ":scriptencoding utf-8" then. 400 401 If you set the 'encoding' option in your |.vimrc|, 402 `:scriptencoding` must be placed after that. E.g.: > 403 set encoding=utf-8 404 scriptencoding utf-8 405 < 406 407 :scriptv[ersion] {version} *:scriptv* *:scriptversion* 408 *E999* *E984* *E1040* 409 Specify the version of Vim for the lines that follow 410 in the same file. Only applies at the toplevel of 411 sourced scripts, not inside functions. 412 413 If {version} is higher than what the current Vim 414 version supports E999 will be given. You either need 415 to rewrite the script to make it work with an older 416 Vim version, or update Vim to a newer version. See 417 |vimscript-version| for what changed between versions. 418 419 :vim9s[cript] [noclear] *:vim9s* *:vim9script* 420 Marks a script file as containing |Vim9-script| 421 commands. Also see |vim9-namespace|. *E1038* 422 Must be the first command in the file. *E1039* 423 For [noclear] see |vim9-reload|. 424 Without the |+eval| feature this changes the syntax 425 for some commands. 426 See |:vim9cmd| for executing one command with Vim9 427 syntax and semantics. 428 429 *:scr* *:scriptnames* 430 :scr[iptnames] List all sourced script names, in the order they were 431 first encountered. The number is used for the script 432 ID |<SID>|. 433 For a script that was used with `import autoload` but 434 was not actually sourced yet an "A" is shown after the 435 script ID. 436 For a script that was referred to by one name but 437 after resolving symbolic links got sourced with 438 another name the other script is after "->". E.g. 439 "20->22" means script 20 was sourced as script 22. 440 Also see `getscriptinfo()`. 441 {not available when compiled without the |+eval| 442 feature} 443 444 :scr[iptnames][!] {scriptId} *:script* 445 Edit script {scriptId}. Although ":scriptnames name" 446 works, using ":script name" is recommended. 447 When the current buffer can't be |abandon|ed and the ! 448 is not present, the command fails. 449 450 *:fini* *:finish* *E168* 451 :fini[sh] Stop sourcing a script. Can only be used in a Vim 452 script file. This is a quick way to skip the rest of 453 the file. If it is used after a |:try| but before the 454 matching |:finally| (if present), the commands 455 following the ":finally" up to the matching |:endtry| 456 are executed first. This process applies to all 457 nested ":try"s in the script. The outermost ":endtry" 458 then stops sourcing the script. 459 460 In |Vim9| script `:finish` cannot be shortened, to 461 improve script readability. 462 463 All commands and command sequences can be repeated by putting them in a named 464 register and then executing it. There are two ways to get the commands in the 465 register: 466 - Use the record command "q". You type the commands once, and while they are 467 being executed they are stored in a register. Easy, because you can see 468 what you are doing. If you make a mistake, "p"ut the register into the 469 file, edit the command sequence, and then delete it into the register 470 again. You can continue recording by appending to the register (use an 471 uppercase letter). 472 - Delete or yank the command sequence into the register. 473 474 Often used command sequences can be put under a function key with the ':map' 475 command. 476 477 An alternative is to put the commands in a file, and execute them with the 478 ':source!' command. Useful for long command sequences. Can be combined with 479 the ':map' command to put complicated commands under a function key. 480 481 The ':source' command reads Ex commands from a file or a buffer line by line. 482 You will have to type any needed keyboard input. The ':source!' command reads 483 from a script file character by character, interpreting each character as if 484 you typed it. 485 486 Example: When you give the ":!ls" command you get the |hit-enter| prompt. If 487 you ':source' a file with the line "!ls" in it, you will have to type the 488 <Enter> yourself. But if you ':source!' a file with the line ":!ls" in it, 489 the next characters from that file are read until a <CR> is found. You will 490 not have to type <CR> yourself, unless ":!ls" was the last line in the file. 491 492 It is possible to put ':source[!]' commands in the script file, so you can 493 make a top-down hierarchy of script files. The ':source' command can be 494 nested as deep as the number of files that can be opened at one time (about 495 15). The ':source!' command can be nested up to 15 levels deep. 496 497 You can use the "<sfile>" string (literally, this is not a special key) inside 498 of the sourced file, in places where a file name is expected. It will be 499 replaced by the file name of the sourced file. For example, if you have a 500 "other.vimrc" file in the same directory as your ".vimrc" file, you can source 501 it from your ".vimrc" file with this command: > 502 :source <sfile>:h/other.vimrc 503 504 In script files terminal-dependent key codes are represented by 505 terminal-independent two character codes. This means that they can be used 506 in the same way on different kinds of terminals. The first character of a 507 key code is 0x80 or 128, shown on the screen as "~@". The second one can be 508 found in the list |key-notation|. Any of these codes can also be entered 509 with CTRL-V followed by the three digit decimal code. This does NOT work for 510 the <t_xx> termcap codes, these can only be used in mappings. 511 512 *:source_crnl* *W15* 513 Win32: Files that are read with ":source" normally have <CR><NL> <EOL>s. 514 These always work. If you are using a file with <NL> <EOL>s (for example, a 515 file made on Unix), this will be recognized if 'fileformats' is not empty and 516 the first line does not end in a <CR>. This fails if the first line has 517 something like ":map <F1> :help^M", where "^M" is a <CR>. If the first line 518 ends in a <CR>, but following ones don't, you will get an error message, 519 because the <CR> from the first lines will be lost. 520 521 Mac Classic: Files that are read with ":source" normally have <CR> <EOL>s. 522 These always work. If you are using a file with <NL> <EOL>s (for example, a 523 file made on Unix), this will be recognized if 'fileformats' is not empty and 524 the first line does not end in a <CR>. Be careful not to use a file with <NL> 525 linebreaks which has a <CR> in first line. 526 527 On other systems, Vim expects ":source"ed files to end in a <NL>. These 528 always work. If you are using a file with <CR><NL> <EOL>s (for example, a 529 file made on MS-Windows), all lines will have a trailing <CR>. This may cause 530 problems for some commands (e.g., mappings). There is no automatic <EOL> 531 detection, because it's common to start with a line that defines a mapping 532 that ends in a <CR>, which will confuse the automaton. 533 534 *line-continuation* 535 Long lines in a ":source"d Ex command script file can be split by inserting 536 a line continuation symbol "\" (backslash) at the start of the next line. 537 There can be white space before the backslash, which is ignored. 538 539 Example: the lines > 540 :set comments=sr:/*,mb:*,el:*/, 541 \://, 542 \b:#, 543 \:%, 544 \n:>, 545 \fb:- 546 are interpreted as if they were given in one line: > 547 :set comments=sr:/*,mb:*,el:*/,://,b:#,:%,n:>,fb:- 548 549 All leading whitespace characters in the line before a backslash are ignored. 550 Note however that trailing whitespace in the line before it cannot be 551 inserted freely; it depends on the position where a command is split up 552 whether additional whitespace is allowed or not. 553 554 When a space is required it's best to put it right after the backslash. A 555 space at the end of a line is hard to see and may be accidentally deleted. > 556 :syn match Comment 557 \ "very long regexp" 558 \ keepend 559 560 In |Vim9| script the backslash can often be omitted, but not always. 561 See |vim9-line-continuation|. 562 563 There is a problem with the ":append" and ":insert" commands: > 564 :1append 565 \asdf 566 . 567 The backslash is seen as a line-continuation symbol, thus this results in the 568 command: > 569 :1appendasdf 570 . 571 To avoid this, add the 'C' flag to the 'cpoptions' option: > 572 :set cpo+=C 573 :1append 574 \asdf 575 . 576 :set cpo-=C 577 578 Note that when the commands are inside a function, you need to add the 'C' 579 flag when defining the function, it is not relevant when executing it. > 580 :set cpo+=C 581 :function Foo() 582 :1append 583 \asdf 584 . 585 :endfunction 586 :set cpo-=C 587 < 588 *line-continuation-comment* 589 To add a comment in between the lines start with '"\ '. Notice the space 590 after the backslash. Example: > 591 let array = [ 592 "\ first entry comment 593 \ 'first', 594 "\ second entry comment 595 \ 'second', 596 \ ] 597 598 Rationale: 599 Most programs work with a trailing backslash to indicate line 600 continuation. Using this in Vim would cause incompatibility with Vi. 601 For example for this Vi mapping: > 602 :map xx asdf\ 603 < Therefore the unusual leading backslash is used. 604 605 Starting a comment in a continuation line results in all following 606 continuation lines to be part of the comment. Since it was like this 607 for a long time, when making it possible to add a comment halfway a 608 sequence of continuation lines, it was not possible to use \", since 609 that was a valid continuation line. Using '"\ ' comes closest, even 610 though it may look a bit weird. Requiring the space after the 611 backslash is to make it very unlikely this is a normal comment line. 612 613 ============================================================================== 614 5. Using Vim packages *packages* 615 616 A Vim package is a directory that contains one or more plugins. The 617 advantages over normal plugins: 618 - A package can be downloaded as an archive and unpacked in its own directory. 619 Thus the files are not mixed with files of other plugins. That makes it 620 easy to update and remove. 621 - A package can be a git, mercurial, etc. repository. That makes it really 622 easy to update. 623 - A package can contain multiple plugins that depend on each other. 624 - A package can contain plugins that are automatically loaded on startup and 625 ones that are only loaded when needed with `:packadd`. 626 627 628 Using a package and loading automatically ~ 629 630 Let's assume your Vim files are in the "~/.vim" directory and you want to add 631 a package from a zip archive "/tmp/foopack.zip": > 632 % mkdir -p ~/.vim/pack/foo 633 % cd ~/.vim/pack/foo 634 % unzip /tmp/foopack.zip 635 636 The directory name "foo" is arbitrary, you can pick anything you like. 637 638 You would now have these files under ~/.vim: 639 pack/foo/README.txt 640 pack/foo/start/foobar/plugin/foo.vim 641 pack/foo/start/foobar/syntax/some.vim 642 pack/foo/opt/foodebug/plugin/debugger.vim 643 644 When Vim starts up, after processing your .vimrc, it scans all directories in 645 'packpath' for plugins under the "pack/*/start" directory. First all those 646 directories are added to 'runtimepath'. Then all the plugins are loaded. 647 See |packload-two-steps| for how these two steps can be useful. 648 649 To allow for calling into package functionality while parsing your .vimrc, 650 |:colorscheme| and |autoload| will both automatically search under 'packpath' 651 as well in addition to 'runtimepath'. See the documentation for each for 652 details. 653 654 In the example Vim will find "pack/foo/start/foobar/plugin/foo.vim" and adds 655 "~/.vim/pack/foo/start/foobar" to 'runtimepath'. 656 657 If the "foobar" plugin kicks in and sets the 'filetype' to "some", Vim will 658 find the syntax/some.vim file, because its directory is in 'runtimepath'. 659 660 Vim will also load ftdetect files, if there are any. 661 662 Note that the files under "pack/foo/opt" are not loaded automatically, only 663 the ones under "pack/foo/start". See |pack-add| below for how the "opt" 664 directory is used. 665 666 Loading packages automatically will not happen if loading plugins is disabled, 667 see |load-plugins|. 668 669 To load packages earlier, so that 'runtimepath' gets updated: > 670 :packloadall 671 This also works when loading plugins is disabled. The automatic loading will 672 only happen once. 673 674 If the package has an "after" directory, that directory is added to the end of 675 'runtimepath', so that anything there will be loaded later. 676 677 678 Using a single plugin and loading it automatically ~ 679 680 If you don't have a package but a single plugin, you need to create the extra 681 directory level: > 682 % mkdir -p ~/.vim/pack/foo/start/foobar 683 % cd ~/.vim/pack/foo/start/foobar 684 % unzip /tmp/someplugin.zip 685 686 You would now have these files: 687 pack/foo/start/foobar/plugin/foo.vim 688 pack/foo/start/foobar/syntax/some.vim 689 690 From here it works like above. 691 692 693 Optional plugins ~ 694 *pack-add* 695 To load an optional plugin from a pack use the `:packadd` command: > 696 :packadd foodebug 697 This searches for "pack/*/opt/foodebug" in 'packpath' and will find 698 ~/.vim/pack/foo/opt/foodebug/plugin/debugger.vim and source it. 699 700 This could be done if some conditions are met. For example, depending on 701 whether Vim supports a feature or a dependency is missing. 702 703 You can also load an optional plugin at startup, by putting this command in 704 your |.vimrc|: > 705 :packadd! foodebug 706 The extra "!" is so that the plugin isn't loaded if Vim was started with 707 |--noplugin|. 708 709 It is perfectly normal for a package to only have files in the "opt" 710 directory. You then need to load each plugin when you want to use it. 711 712 713 Where to put what ~ 714 715 Since color schemes, loaded with `:colorscheme`, are found below 716 "pack/*/start" and "pack/*/opt", you could put them anywhere. We recommend 717 you put them below "pack/*/opt", for example 718 ".vim/pack/mycolors/opt/dark/colors/very_dark.vim". 719 720 Filetype plugins should go under "pack/*/start", so that they are always 721 found. Unless you have more than one plugin for a file type and want to 722 select which one to load with `:packadd`. E.g. depending on the compiler 723 version: > 724 if foo_compiler_version > 34 725 packadd foo_new 726 else 727 packadd foo_old 728 endif 729 730 The "after" directory is most likely not useful in a package. It's not 731 disallowed though. 732 733 ============================================================================== 734 6. Creating Vim packages *package-create* 735 736 This assumes you write one or more plugins that you distribute as a package. 737 738 If you have two unrelated plugins you would use two packages, so that Vim 739 users can choose what they include or not. Or you can decide to use one 740 package with optional plugins, and tell the user to add the preferred ones 741 with `:packadd`. 742 743 Decide how you want to distribute the package. You can create an archive or 744 you could use a repository. An archive can be used by more users, but is a 745 bit harder to update to a new version. A repository can usually be kept 746 up-to-date easily, but it requires a program like "git" to be available. 747 You can do both, github can automatically create an archive for a release. 748 749 Your directory layout would be like this: 750 start/foobar/plugin/foo.vim " always loaded, defines commands 751 start/foobar/plugin/bar.vim " always loaded, defines commands 752 start/foobar/autoload/foo.vim " loaded when foo command used 753 start/foobar/doc/foo.txt " help for foo.vim 754 start/foobar/doc/tags " help tags 755 start/foobar/lang/<lang_id>/LC_MESSAGES/foobar.mo 756 " messages for the plugin in the 757 " <lang_id> language. These files are 758 " optional. 759 opt/fooextra/plugin/extra.vim " optional plugin, defines commands 760 opt/fooextra/autoload/extra.vim " loaded when extra command used 761 opt/fooextra/doc/extra.txt " help for extra.vim 762 opt/fooextra/doc/tags " help tags 763 764 This allows for the user to do: > 765 mkdir ~/.vim/pack 766 cd ~/.vim/pack 767 git clone https://github.com/you/foobar.git myfoobar 768 < 769 Here "myfoobar" is a name that the user can choose, the only condition is that 770 it differs from other packages. 771 772 In your documentation you explain what the plugins do, and tell the user how 773 to load the optional plugin: > 774 :packadd! fooextra 775 < 776 You could add this packadd command in one of your plugins, to be executed when 777 the optional plugin is needed. 778 779 *package-doc* *package-documentation* 780 Run the `:helptags` command to generate the doc/tags file. Including this 781 generated file in the package means that the user can drop the package in the 782 pack directory and the help command works right away. Don't forget to re-run 783 the command after changing the plugin help: > 784 :helptags path/start/foobar/doc 785 :helptags path/opt/fooextra/doc 786 < 787 *package-translation* 788 In order for a plugin to display translated messages, a few steps are 789 required. 790 The author of the plugin who likes to translate messages must define the name 791 of the package and the location of the directory where the translations can be 792 found using the |bindtextdomain()| function: > 793 :call bindtextdomain("foobar", 794 \ fnamemodify(expand("<script>"), ':p:h') .. '/../lang/') 795 < 796 Where: 797 "foobar" is the unique package identifier by which the |gettext()| 798 function will later search for translation strings for this 799 plugin. 800 "lang/" is the relative or absolute path to the directory structure 801 where the translation file is located. 802 803 The directory structure where the message translation files should be placed 804 is (from the top-level directory of the package): 805 "lang/<lang_id>/LC_MESSAGES". For the format of <lang_id> see |multi-lang|. 806 This function needs to be called only once during the initialization of the 807 plugin. 808 Once this is done, the |gettext()| function can be used to retrieve translated 809 messages: > 810 :echo gettext("Hello", "foobar") 811 < 812 Where: 813 "Hello" the message "Hello" to be translated into the user's language 814 |:lang| 815 "foobar" the package identifier, which was previously defined using the 816 |bindtextdomain()| function. 817 818 After that you need to create a template file for translation - POT-file. 819 To do this, execute the following commands (using the Vim repository): > 820 cd ~/forkvim/src/po 821 make -f Makefile "PLUGPACKAGE={package}" \ 822 "PO_PLUG_INPUTLIST={path/to/scripts-that-need-translations.vim}" \ 823 ["POT_PLUGPACKAGE_PATH={path/where/to/write/{package}.pot}" \] 824 ["VIMPROG={path/to/vim} \] 825 {package}.pot 826 < 827 Where: 828 PLUGPACKAGE A variable containing the name of the package that we 829 specified in the |bindtextdomain()| and 830 |gettext()| functions, for example, "foobar". 831 PO_PLUG_INPUTLIST A variable containing scripts that have strings 832 to translate, i.e. where we specified the |gettext()| 833 function. Scripts are specified with an absolute 834 or relative path. Example: 835 start/foobar/plugin/bar.vim 836 use blanks to separate scripts. 837 POT_PLUGPACKAGE_PATH A variable containing the directory where the prepared 838 POT file will be saved. This is not a required 839 variable, if no directory is specified, then the POT 840 file will be placed in the "src/po" directory. 841 VIMPROG A variable containing a directory with a working Vim. 842 If the Vim editor is already built and installed, and 843 is contained in the $PATH environment variable, 844 then you can specify just the name of the vim 845 executable. 846 {package}.pot This is the Target. It is specified as the name of 847 the package, for example, "foobar" with the addition 848 of the .pot extension. 849 Once a POT file is created, its contents are copied into separate PO files for 850 each language for which the translation will be prepared. 851 852 When the translation is finished, it is necessary to convert the PO files into 853 binary MO-files format and place these MO-files into the "lang/" directory, 854 the structure of which we created earlier. 855 To do this, run the following commands: 856 > 857 cd ~/forkvim/src/po 858 make -f Makefile "PLUGPACKAGE={package}" \ 859 "PO_PLUGPACKAGE={path/to/{lang}.po}" \ 860 ["MO_PLUGPACKAGE_PATH={path/to/lang/<lang_id>/LC_MESSAGES}" \] 861 {package}.mo 862 < 863 Where: 864 PLUGPACKAGE A variable containing the name of the package that we 865 specified in the |bindtextdomain()| and |gettext()| 866 functions, for example, "foobar". 867 PO_PLUGPACKAGE A variable containing a PO file. The file is 868 specified with an absolute or relative path. For 869 example, "~/myproject/translate/en.po" 870 MO_PLUGPACKAGE_PATH A variable containing the structure of the "lang/" 871 directory, where the file with translations will be 872 placed, for example, "foobar.mo". This is not 873 a required variable, if the directory is not 874 specified, the MO file will be saved in the "src/po" 875 directory. 876 {package}.mo This is the Target. It is specified as the name of 877 the package, for example, "foobar" with the addition 878 of the .mo extension. 879 880 *package-translate_example* 881 Let's show it all on some concrete example and translate the 882 "ftplugin/aap.vim" file into Russian and German. 883 884 First, let's prepare the "aap.vim" file, specifying |bindtextdomain()| and 885 |gettext()| function calls in it. 886 > 887 " Only do this when not done yet for this buffer 888 if exists("b:did_ftplugin") 889 finish 890 endif 891 892 " Don't load another plugin for this buffer 893 let b:did_ftplugin = 1 894 call bindtextdomain("aap", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/') 895 896 " Reset 'formatoptions', 'comments', 'commentstring' and 'expandtab' to undo 897 " this plugin. 898 let b:undo_ftplugin = "setl fo< com< cms< et<" 899 900 " Set 'formatoptions' to break comment lines but not other lines, 901 " and insert the comment leader when hitting <CR> or using "o". 902 setlocal fo-=t fo+=croql 903 904 " Set 'comments' to format dashed lists in comments. 905 setlocal comments=s:#\ -,m:#\ \ ,e:#,n:#,fb:- 906 setlocal commentstring=#\ %s 907 908 " Expand tabs to spaces to avoid trouble. 909 setlocal expandtab 910 911 if (has("gui_win32") || has("gui_gtk")) && !exists("b:browsefilter") 912 let b:browsefilter = gettext("Aap Recipe Files (*.aap)\t*.aap\n", "aap") 913 if has("win32") 914 let b:browsefilter ..= gettext("All Files (*.*)\t*\n", "aap") 915 else 916 let b:browsefilter ..= gettext("All Files (*)\t*\n", "aap") 917 endif 918 let b:undo_ftplugin ..= " | unlet! b:browsefilter" 919 endif 920 < 921 Now let's create a POT file for it (example uses Windows paths): 922 > 923 cd /d f:\forkvim\src\po 924 (the following command must be entered in one line, here it is separated for example) 925 nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap" 926 "PO_PLUG_INPUTLIST=d:\Programs\vim\vim91\ftplugin\aap.vim" 927 "POT_PLUGPACKAGE_PATH=e:\project\translate\plugins" 928 "VIMPROG=d:\Programs\vim\vim91\vim.exe" 929 aap.pot 930 < 931 After the POT file of our package is created, go to the directory where we 932 saved it and perform the translation. 933 > 934 cd /d e:\project\translate\plugins 935 copy aap.pot ru.po 936 copy aap.pot de.po 937 < 938 We have prepared a PO file with a translation into Russian: 939 # Test plugins translate ~ 940 # ~ 941 msgid "" ~ 942 msgstr "" ~ 943 "Project-Id-Version: aap\n" ~ 944 "Report-Msgid-Bugs-To: \n" ~ 945 "POT-Creation-Date: 2024-06-23 14:58+0300\n" ~ 946 "PO-Revision-Date: 2024-06-23 14:58+0300\n" ~ 947 "Last-Translator: Restorer\n" ~ 948 "Language-Team: RuVim\n" ~ 949 "Language: ru\n" ~ 950 "MIME-Version: 1.0\n" ~ 951 "Content-Type: text/plain; charset=UTF-8\n" ~ 952 "Content-Transfer-Encoding: 8bit\n" ~ 953 954 #: ../../runtime/ftplugin/aap.vim:32 ~ 955 msgid "Aap Recipe Files (*.aap)\t*.aap\n" ~ 956 msgstr "Файлы инструкций Aap (*.aap)\t*.aap\n" ~ 957 958 #: ../../runtime/ftplugin/aap.vim:34 ~ 959 msgid "All Files (*.*)\t*\n" ~ 960 msgstr "Все файлы (*.*)\t*\n" ~ 961 962 #: ../../runtime/ftplugin/aap.vim:36 ~ 963 msgid "All Files (*)\t*\n" ~ 964 msgstr "Все файлы (*)\t*\n" ~ 965 966 And the PO file in German: 967 # Test plugins translate~ 968 #~ 969 msgid ""~ 970 msgstr ""~ 971 "Project-Id-Version: aap\n"~ 972 "Report-Msgid-Bugs-To: \n"~ 973 "POT-Creation-Date: 2024-06-23 14:58+0300\n"~ 974 "PO-Revision-Date: 2024-06-24 13:11+0300\n"~ 975 "Last-Translator: Restorer\n"~ 976 "Language-Team: German\n"~ 977 "Language: de\n"~ 978 "MIME-Version: 1.0\n"~ 979 "Content-Type: text/plain; charset=UTF-8\n"~ 980 "Content-Transfer-Encoding: 8bit\n"~ 981 982 #: ../../runtime/ftplugin/aap.vim:32~ 983 msgid "Aap Recipe Files (*.aap)\t*.aap\n"~ 984 msgstr "Aap-Rezeptdateien (*.aap)\t*.aap\n"~ 985 986 #: ../../runtime/ftplugin/aap.vim:34~ 987 msgid "All Files (*.*)\t*\n"~ 988 msgstr "Alle Dateien (*.*)\t*.*\n"~ 989 990 #: ../../runtime/ftplugin/aap.vim:36~ 991 msgid "All Files (*)\t*\n"~ 992 msgstr "Alle Dateien (*)\t*\n"~ 993 994 Now convert these files into MO files so that |gettext()| can display message 995 translations. Note that since this is not a specialized plugin package, we 996 will put the MO files in the "lang/" directory of the Vim editor. 997 Type the following commands: 998 > 999 cd /d f:\forkvim\src\po 1000 < (the following command must be entered in one line, here it is separated for example) 1001 For Russian: > 1002 nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap" 1003 "PO_PLUGPACKAGE=e:\project\translate\plugins\ru.po" 1004 "MO_PLUGPACKAGE_PATH=d:\Programs\vim\vim91\lang\ru\LC_MESSAGES" 1005 aap.mo 1006 < For German: > 1007 nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap" 1008 "PO_PLUGPACKAGE=e:\project\translate\plugins\de.po" 1009 "MO_PLUGPACKAGE_PATH=d:\Programs\vim\vim91\lang\de\LC_MESSAGES" 1010 aap.mo 1011 < 1012 That's it, the translations are ready and you can see the plugin's messages 1013 in your native language. 1014 1015 Let's also try to translate a plugin package. For example, when a package 1016 contains several scripts containing strings that need to be translated. 1017 For example, let's translate the "netrw" package into Japanese. 1018 For this example, we will translate only a few lines from this package. 1019 Let's prepare the scripts where we need to translate the message strings. 1020 1021 The file "autoload\netrw.vim": 1022 > 1023 " Load Once: 1024 if &cp || exists("g:loaded_netrw") 1025 finish 1026 endif 1027 call bindtextdomain("netrw", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/') 1028 1029 " Check that vim has patches that netrw requires. 1030 " Patches needed for v7.4: 1557, and 213. 1031 " (netrw will benefit from vim's having patch#656, too) 1032 let s:needspatches=[1557,213] 1033 if exists("s:needspatches") 1034 for ptch in s:needspatches 1035 if v:version < 704 || (v:version == 704 && !has("patch".ptch)) 1036 if !exists("s:needpatch{ptch}") 1037 unsilent echomsg gettext("***sorry*** this version of netrw requires vim v7.4 with patch#", "netrw") .. ptch 1038 endif 1039 let s:needpatch{ptch}= 1 1040 finish 1041 endif 1042 endfor 1043 endif 1044 < 1045 The file "autoload\netrwSettings.vim": 1046 > 1047 " Load Once: 1048 if exists("g:loaded_netrwSettings") || &cp 1049 finish 1050 endif 1051 call bindtextdomain("netrw", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/') 1052 let g:loaded_netrwSettings = "v18" 1053 if v:version < 700 1054 echohl WarningMsg 1055 echo gettext("***warning*** this version of netrwSettings needs vim 7.0", "netrw") 1056 echohl Normal 1057 finish 1058 endif 1059 < 1060 Now we will prepare a POT file for further translation of messages. 1061 Execute the following commands: 1062 > 1063 cd ~/forkvim/src/po 1064 make -f Makefile "VIMPROG=/usr/local/bin/vim" "PLUGPACKAGE=netrw" \ 1065 "POT_PLUGPACKAGE_PATH=~/project/translate/plugins" \ 1066 "PO_PLUG_INPUTLIST=../../runtime/autoload/netrw.vim 1067 ../../runtime/autoload/netrwSettings.vim" \ 1068 netrw.pot 1069 < 1070 Go to the directory with the POT file and make the translation: 1071 > 1072 cd ~/project/translate/plugins 1073 cp ./netrw.pot ja.po 1074 < 1075 When we have the translation ready in the "ja.po" file: 1076 # Test plugins translate ~ 1077 # ~ 1078 msgid "" ~ 1079 msgstr "" ~ 1080 "Project-Id-Version: netrw\n" ~ 1081 "Report-Msgid-Bugs-To: \n" ~ 1082 "POT-Creation-Date: 2024-06-23 17:14+0300\n" ~ 1083 "PO-Revision-Date: 2024-06-23 17:14+0300\n" ~ 1084 "Last-Translator: Restorer\n" ~ 1085 "Language-Team: Japanese\n" ~ 1086 "Language: ja\n" ~ 1087 "MIME-Version: 1.0\n" ~ 1088 "Content-Type: text/plain; charset=UTF-8\n" ~ 1089 "Content-Transfer-Encoding: 8bit\n" ~ 1090 1091 #: ../../runtime/autoload/netrw.vim:51 ~ 1092 msgid "***sorry*** this version of netrw requires vim v7.4 with patch#" ~ 1093 msgstr "" ~ 1094 "***申し訳ありません***このバージョンのnetrwには、パッチ付きのvim v7.4が必要です#" ~ 1095 1096 #: ../../runtime/autoload/netrwSettings.vim:28 ~ 1097 msgid "***warning*** this version of netrwSettings needs vim 7.0" ~ 1098 msgstr "***警告***このバージョンのnetrwSettingsにはvim7.0が必要です" ~ 1099 1100 Convert ja.po to a MO file: 1101 > 1102 cd ~/forkvim/src/po 1103 make -f Makefile "PLUGPACKAGE=netrw" \ 1104 "PO_PLUGPACKAGE=~/project/translate/plugins/ja.po" \ 1105 "MO_PLUGPACKAGE_PATH=/usr/local/share/vim/vim91/lang/ja/LC_MESSAGES" \ 1106 netrw.mo 1107 < 1108 Executing those steps will allow you to get translation of any third-party 1109 plug-in packages. 1110 1111 Dependencies between plugins ~ 1112 *packload-two-steps* 1113 Suppose you have two plugins that depend on the same functionality. You can 1114 put the common functionality in an autoload directory, so that it will be 1115 found automatically. Your package would have these files: 1116 1117 pack/foo/start/one/plugin/one.vim > 1118 call foolib#getit() 1119 < pack/foo/start/two/plugin/two.vim > 1120 call foolib#getit() 1121 < pack/foo/start/lib/autoload/foolib.vim > 1122 func foolib#getit() 1123 1124 This works, because loading packages will first add all found directories to 1125 'runtimepath' before sourcing the plugins. 1126 1127 ============================================================================== 1128 7. Debugging scripts *debug-scripts* 1129 1130 Besides the obvious messages that you can add to your scripts to find out what 1131 they are doing, Vim offers a debug mode. This allows you to step through a 1132 sourced file or user function and set breakpoints. 1133 1134 NOTE: The debugging mode is far from perfect. Debugging will have side 1135 effects on how Vim works. You cannot use it to debug everything. For 1136 example, the display is messed up by the debugging messages. 1137 1138 An alternative to debug mode is setting the 'verbose' option. With a bigger 1139 number it will give more verbose messages about what Vim is doing. 1140 1141 1142 STARTING DEBUG MODE *debug-mode* 1143 1144 To enter debugging mode use one of these methods: 1145 1. Start Vim with the |-D| argument: > 1146 vim -D file.txt 1147 < Debugging will start as soon as the first vimrc file is sourced. This is 1148 useful to find out what is happening when Vim is starting up. A side 1149 effect is that Vim will switch the terminal mode before initialisations 1150 have finished, with unpredictable results. 1151 For a GUI-only version (Windows, Macintosh) the debugging will start as 1152 soon as the GUI window has been opened. To make this happen early, add a 1153 ":gui" command in the vimrc file. 1154 *:debug* 1155 2. Run a command with ":debug" prepended. Debugging will only be done while 1156 this command executes. Useful for debugging a specific script or user 1157 function. And for scripts and functions used by autocommands. Example: > 1158 :debug edit test.txt.gz 1159 1160 3. Set a breakpoint in a sourced file or user function. You could do this in 1161 the command line: > 1162 vim -c "breakadd file */explorer.vim" . 1163 < This will run Vim and stop in the first line of the "explorer.vim" script. 1164 Breakpoints can also be set while in debugging mode. 1165 1166 In debugging mode every executed command is displayed before it is executed. 1167 Comment lines, empty lines and lines that are not executed are skipped. When 1168 a line contains two commands, separated by "|", each command will be displayed 1169 separately. 1170 1171 1172 DEBUG MODE 1173 1174 Once in debugging mode, the usual Ex commands can be used. For example, to 1175 inspect the value of a variable: > 1176 echo idx 1177 When inside a user function, this will print the value of the local variable 1178 "idx". Prepend "g:" to get the value of a global variable: > 1179 echo g:idx 1180 All commands are executed in the context of the current function or script. 1181 You can also set options, for example setting or resetting 'verbose' will show 1182 what happens, but you might want to set it just before executing the lines you 1183 are interested in: > 1184 :set verbose=20 1185 1186 Commands that require updating the screen should be avoided, because their 1187 effect won't be noticed until after leaving debug mode. For example: > 1188 :help 1189 won't be very helpful. 1190 1191 There is a separate command-line history for debug mode. 1192 1193 NOTE: In Vim9 script, if a command is written at the script level and 1194 continues on the next line, not using the old way with a backslash for line 1195 continuation, only the first line is printed before the debugging prompt. 1196 1197 The line number for a function line is relative to the start of the function. 1198 If you have trouble figuring out where you are, edit the file that defines 1199 the function in another Vim, search for the start of the function and do 1200 "99j". Replace "99" with the line number. 1201 1202 Additionally, these commands can be used: 1203 *>cont* 1204 cont Continue execution until the next breakpoint is hit. 1205 *>quit* 1206 quit Abort execution. This is like using CTRL-C, some 1207 things might still be executed, doesn't abort 1208 everything. Still stops at the next breakpoint. 1209 *>next* 1210 next Execute the command and come back to debug mode when 1211 it's finished. This steps over user function calls 1212 and sourced files. 1213 *>step* 1214 step Execute the command and come back to debug mode for 1215 the next command. This steps into called user 1216 functions and sourced files. 1217 *>interrupt* 1218 interrupt This is like using CTRL-C, but unlike ">quit" comes 1219 back to debug mode for the next command that is 1220 executed. Useful for testing |:finally| and |:catch| 1221 on interrupt exceptions. 1222 *>finish* 1223 finish Finish the current script or user function and come 1224 back to debug mode for the command after the one that 1225 sourced or called it. 1226 *>bt* 1227 *>backtrace* 1228 *>where* 1229 backtrace Show the call stacktrace for current debugging 1230 session. 1231 bt 1232 where 1233 *>frame* 1234 frame N Goes to N backtrace level. + and - signs make movement 1235 relative. E.g., ":frame +3" goes three frames up. 1236 *>up* 1237 up Goes one level up from call stacktrace. 1238 *>down* 1239 down Goes one level down from call stacktrace. 1240 1241 About the additional commands in debug mode: 1242 - There is no command-line completion for them, you get the completion for the 1243 normal Ex commands only. 1244 - You can shorten them, up to a single character, unless more than one command 1245 starts with the same letter. "f" stands for "finish", use "fr" for "frame". 1246 - Hitting <CR> will repeat the previous one. When doing another command, this 1247 is reset (because it's not clear what you want to repeat). 1248 - When you want to use the Ex command with the same name, prepend a colon: 1249 ":cont", ":next", ":finish" (or shorter). 1250 *vim9-debug* 1251 When debugging a compiled :def function, "step" will stop before every 1252 executed line, not every single instruction. Thus it works mostly like a not 1253 compiled function. Access to local variables is limited you can use: > 1254 echo varname 1255 But not much else. 1256 When executing a command that is not a specific bytecode instruction but 1257 executed like a normal Ex command, "step" will stop once in the compiled 1258 context, where local variables can be inspected, and once just before 1259 executing the command. 1260 1261 In a :def function variables that haven't been declared yet cannot be 1262 inspected. Variables that have been declared can be inspected, also when the 1263 block they were declared in has finished. In commands this would not be 1264 possible, thus is slightly misleading (but can be useful). 1265 1266 The backtrace shows the hierarchy of function calls, e.g.: 1267 >bt ~ 1268 3 function One[3] ~ 1269 2 Two[3] ~ 1270 ->1 Three[3] ~ 1271 0 Four ~ 1272 line 1: let four = 4 ~ 1273 1274 The "->" points to the current frame. Use "up", "down" and "frame N" to 1275 select another frame. 1276 1277 In the current frame you can evaluate the local function variables. There is 1278 no way to see the command at the current line yet. 1279 1280 1281 DEFINING BREAKPOINTS 1282 *:breaka* *:breakadd* 1283 :breaka[dd] func [lnum] {name} 1284 Set a breakpoint in a function. Example: > 1285 :breakadd func Explore 1286 < Doesn't check for a valid function name, thus the breakpoint 1287 can be set before the function is defined. 1288 1289 :breaka[dd] file [lnum] {name} 1290 Set a breakpoint in a sourced file. Example: > 1291 :breakadd file 43 .vimrc 1292 1293 :breaka[dd] here 1294 Set a breakpoint in the current line of the current file. 1295 Like doing: > 1296 :breakadd file <cursor-line> <current-file> 1297 < Note that this only works for commands that are executed when 1298 sourcing the file, not for a function defined in that file. 1299 1300 :breaka[dd] expr {expression} 1301 Sets a breakpoint, that will break whenever the {expression} 1302 evaluates to a different value. Example: > 1303 :breakadd expr g:lnum 1304 < Will break, whenever the global variable lnum changes. 1305 1306 Errors in evaluation are suppressed, you can use the name of a 1307 variable that does not exist yet. This also means you will 1308 not notice anything if the expression has a mistake. 1309 1310 Note if you watch a |script-variable| this will break 1311 when switching scripts, since the script variable is only 1312 valid in the script where it has been defined and if that 1313 script is called from several other scripts, this will stop 1314 whenever that particular variable will become visible or 1315 inaccessible again. 1316 1317 The [lnum] is the line number of the breakpoint. Vim will stop at or after 1318 this line. When omitted line 1 is used. 1319 1320 *:debug-name* 1321 {name} is a pattern that is matched with the file or function name. The 1322 pattern is like what is used for autocommands. There must be a full match (as 1323 if the pattern starts with "^" and ends in "$"). A "*" matches any sequence 1324 of characters. 'ignorecase' is not used, but "\c" can be used in the pattern 1325 to ignore case |/\c|. Don't include the () for the function name! 1326 1327 The match for sourced scripts is done against the full file name. If no path 1328 is specified the current directory is used. Examples: > 1329 breakadd file explorer.vim 1330 matches "explorer.vim" in the current directory. > 1331 breakadd file *explorer.vim 1332 matches ".../plugin/explorer.vim", ".../plugin/iexplorer.vim", etc. > 1333 breakadd file */explorer.vim 1334 matches ".../plugin/explorer.vim" and "explorer.vim" in any other directory. 1335 1336 The match for functions is done against the name as it's shown in the output 1337 of ":function". However, for local functions the script-specific prefix such 1338 as "<SNR>99_" is ignored to make it easier to match script-local functions 1339 without knowing the ID of the script. 1340 1341 Note that functions are first loaded and later executed. When they are loaded 1342 the "file" breakpoints are checked, when they are executed the "func" 1343 breakpoints. 1344 1345 1346 DELETING BREAKPOINTS 1347 *:breakd* *:breakdel* *E161* 1348 :breakd[el] {nr} 1349 Delete breakpoint {nr}. Use |:breaklist| to see the number of 1350 each breakpoint. 1351 1352 :breakd[el] * 1353 Delete all breakpoints. 1354 1355 :breakd[el] func [lnum] {name} 1356 Delete a breakpoint in a function. 1357 1358 :breakd[el] file [lnum] {name} 1359 Delete a breakpoint in a sourced file. 1360 1361 :breakd[el] here 1362 Delete a breakpoint at the current line of the current file. 1363 1364 When [lnum] is omitted, the first breakpoint in the function or file is 1365 deleted. 1366 The {name} must be exactly the same as what was typed for the ":breakadd" 1367 command. "explorer", "*explorer.vim" and "*explorer*" are different. 1368 1369 1370 LISTING BREAKPOINTS 1371 *:breakl* *:breaklist* 1372 :breakl[ist] 1373 List all breakpoints. 1374 1375 1376 OBSCURE 1377 1378 *:debugg* *:debuggreedy* 1379 :debugg[reedy] 1380 Read debug mode commands from the normal input stream, instead 1381 of getting them directly from the user. Only useful for test 1382 scripts. Example: > 1383 echo 'q^Mq' | vim -e -s -c debuggreedy -c 'breakadd file script.vim' -S script.vim 1384 1385 :0debugg[reedy] 1386 Undo ":debuggreedy": get debug mode commands directly from the 1387 user, don't use typeahead for debug commands. 1388 1389 ============================================================================== 1390 8. Profiling *profile* *profiling* 1391 1392 Profiling means that Vim measures the time that is spent on executing 1393 functions and/or scripts. The |+profile| feature is required for this. 1394 It is included when Vim was compiled with "huge" features. 1395 1396 You can also use the |reltime()| function to measure time. This only requires 1397 the |+reltime| feature, which is present in more builds. 1398 1399 For profiling syntax highlighting see |:syntime|. 1400 1401 For example, to profile the one_script.vim script file: > 1402 :profile start /tmp/one_script_profile 1403 :profile file one_script.vim 1404 :source one_script.vim 1405 :exit 1406 1407 1408 :prof[ile] start {fname} *:prof* *:profile* *E750* 1409 Start profiling, write the output in {fname} upon exit or when 1410 a `:profile stop` or `:profile dump` command is invoked. 1411 "~/" and environment variables in {fname} will be expanded. 1412 If {fname} already exists it will be silently overwritten. 1413 The variable |v:profiling| is set to one. 1414 1415 :prof[ile] stop 1416 Write the collected profiling information to the logfile and 1417 stop profiling. You can use the `:profile start` command to 1418 clear the profiling statistics and start profiling again. 1419 1420 :prof[ile] pause 1421 Stop profiling until the next `:profile continue` command. 1422 Can be used when doing something that should not be counted 1423 (e.g., an external command). Does not nest. 1424 1425 :prof[ile] continue 1426 Continue profiling after `:profile pause`. 1427 1428 :prof[ile] func {pattern} 1429 Profile function that matches the pattern {pattern}. 1430 See |:debug-name| for how {pattern} is used. 1431 1432 :prof[ile][!] file {pattern} 1433 Profile script file that matches the pattern {pattern}. 1434 See |:debug-name| for how {pattern} is used. 1435 This only profiles the script itself, not the functions 1436 defined in it. 1437 When the [!] is added then all functions defined in the script 1438 will also be profiled. 1439 Note that profiling only starts when the script is loaded 1440 after this command. A :profile command in the script itself 1441 won't work. 1442 1443 :prof[ile] dump 1444 Write the current state of profiling to the logfile 1445 immediately. After running this command, Vim continues to 1446 collect the profiling statistics. 1447 1448 :profd[el] ... *:profd* *:profdel* 1449 Stop profiling for the arguments specified. See |:breakdel| 1450 for the arguments. Examples: > 1451 profdel func MyFunc 1452 profdel file MyScript.vim 1453 profdel here 1454 1455 You must always start with a ":profile start fname" command. The resulting 1456 file is written when Vim exits. For example, to profile one specific 1457 function: > 1458 profile start /tmp/vimprofile 1459 profile func MyFunc 1460 1461 Here is an example of the output, with line 1462 numbers prepended for the explanation: 1463 1464 1 FUNCTION Test2() ~ 1465 2 Called 1 time ~ 1466 3 Total time: 0.155251 ~ 1467 4 Self time: 0.002006 ~ 1468 5 ~ 1469 6 count total (s) self (s) ~ 1470 7 9 0.000096 for i in range(8) ~ 1471 8 8 0.153655 0.000410 call Test3() ~ 1472 9 8 0.000070 endfor ~ 1473 10 " Ask a question ~ 1474 11 1 0.001341 echo input("give me an answer: ") ~ 1475 1476 The header (lines 1-4) gives the time for the whole function. The "Total" 1477 time is the time passed while the function was executing. The "Self" time is 1478 the "Total" time reduced by time spent in: 1479 - other user defined functions 1480 - sourced scripts 1481 - executed autocommands 1482 - external (shell) commands 1483 1484 Lines 7-11 show the time spent in each executed line. Lines that are not 1485 executed do not count. Thus a comment line is never counted. 1486 1487 The Count column shows how many times a line was executed. Note that the 1488 "for" command in line 7 is executed one more time as the following lines. 1489 That is because the line is also executed to detect the end of the loop. 1490 1491 The time Vim spends waiting for user input isn't counted at all. Thus how 1492 long you take to respond to the input() prompt is irrelevant. 1493 1494 Profiling should give a good indication of where time is spent, but keep in 1495 mind there are various things that may clobber the results: 1496 1497 - The accuracy of the time measured depends on the gettimeofday(), or 1498 clock_gettime() if available, system function. The accuracy ranges from 1499 1/100 second to nanoseconds. With clock_gettime() the times are displayed 1500 in nanoseconds, otherwise microseconds. You can use `has("prof_nsec")`. 1501 1502 - Real elapsed time is measured, if other processes are busy they may cause 1503 delays at unpredictable moments. You may want to run the profiling several 1504 times and use the lowest results. 1505 1506 - If you have several commands in one line you only get one time. Split the 1507 line to see the time for the individual commands. 1508 1509 - The time of the lines added up is mostly less than the time of the whole 1510 function. There is some overhead in between. 1511 1512 - Functions that are deleted before Vim exits will not produce profiling 1513 information. You can check the |v:profiling| variable if needed: > 1514 :if !v:profiling 1515 : delfunc MyFunc 1516 :endif 1517 < 1518 - Profiling may give weird results on multi-processor systems, when sleep 1519 mode kicks in or the processor frequency is reduced to save power. 1520 1521 - The "self" time is wrong when a function is used recursively. 1522 1523 1524 vim:tw=78:ts=8:noet:ft=help:norl: