vim: runtime/doc/repeat.txt annotate

annotate runtime/doc/repeat.txt @ 29236:0eef32b4ebbc

Update runtime files Commit: https://github.com/vim/vim/commit/d799daa660b8821943cbe1682f00da9e812dd48c Author: Bram Moolenaar <Bram@vim.org> Date: Mon Jun 20 11:17:32 2022 +0100 Update runtime files

author	Bram Moolenaar <Bram@vim.org>
date	Mon, 20 Jun 2022 12:30:06 +0200
parents	6dd88e45d47d
children	f8116058ca76

rev	line source
29236 0eef32b4ebbc Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28379 diff changeset	1 repeat.txt For Vim version 8.2. Last change: 2022 Jun 18
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	2
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	3
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	4 VIM REFERENCE MANUAL by Bram Moolenaar
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	5
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	6
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	7 Repeating commands, Vim scripts and debugging repeating
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	8
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	9 Chapter 26 of the user manual introduces repeating \|usr_26.txt\|.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	10
8748 b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	11 1. Single repeats \|single-repeat\|
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	12 2. Multiple repeats \|multi-repeat\|
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	13 3. Complex repeats \|complex-repeat\|
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	14 4. Using Vim scripts \|using-scripts\|
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	15 5. Using Vim packages \|packages\|
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	16 6. Creating Vim packages \|package-create\|
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	17 7. Debugging scripts \|debug-scripts\|
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	18 8. Profiling \|profiling\|
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	19
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	20 ==============================================================================
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	21 1. Single repeats single-repeat
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	22
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	23 .
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	24 . Repeat last change, with count replaced with [count].
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	25 Also repeat a yank command, when the 'y' flag is
22 cc049b00ee70 updated for version 7.0014 vimboss parents: 11 diff changeset	26 included in 'cpoptions'. Does not repeat a
cc049b00ee70 updated for version 7.0014 vimboss parents: 11 diff changeset	27 command-line command.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	28
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	29 Simple changes can be repeated with the "." command. Without a count, the
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	30 count of the last change is used. If you enter a count, it will replace the
5663 1dea14d4c738 Update runtime files. Add support for systemverilog. Bram Moolenaar <bram@vim.org> parents: 5294 diff changeset	31 last one. \|v:count\| and \|v:count1\| will be set.
1dea14d4c738 Update runtime files. Add support for systemverilog. Bram Moolenaar <bram@vim.org> parents: 5294 diff changeset	32
1dea14d4c738 Update runtime files. Add support for systemverilog. Bram Moolenaar <bram@vim.org> parents: 5294 diff changeset	33 If the last change included a specification of a numbered register, the
1dea14d4c738 Update runtime files. Add support for systemverilog. Bram Moolenaar <bram@vim.org> parents: 5294 diff changeset	34 register number will be incremented. See \|redo-register\| for an example how
1dea14d4c738 Update runtime files. Add support for systemverilog. Bram Moolenaar <bram@vim.org> parents: 5294 diff changeset	35 to use this.
1dea14d4c738 Update runtime files. Add support for systemverilog. Bram Moolenaar <bram@vim.org> parents: 5294 diff changeset	36
1dea14d4c738 Update runtime files. Add support for systemverilog. Bram Moolenaar <bram@vim.org> parents: 5294 diff changeset	37 Note that when repeating a command that used a Visual selection, the same SIZE
1dea14d4c738 Update runtime files. Add support for systemverilog. Bram Moolenaar <bram@vim.org> parents: 5294 diff changeset	38 of area is used, see \|visual-repeat\|.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	39
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	40 @:
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	41 @: Repeat last command-line [count] times.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	42 {not available when compiled without the
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	43 \|+cmdline_hist\| feature}
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	44
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	45
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	46 ==============================================================================
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	47 2. Multiple repeats multi-repeat
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	48
11494 8e5ec22db3d8 patch 8.0.0630: it is not easy to work on lines without a match Christian Brabandt <cb@256bit.org> parents: 10895 diff changeset	49 :g :global E148
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	50 :[range]g[lobal]/{pattern}/[cmd]
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	51 Execute the Ex command [cmd] (default ":p") on the
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	52 lines within [range] where {pattern} matches.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	53
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	54 :[range]g[lobal]!/{pattern}/[cmd]
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	55 Execute the Ex command [cmd] (default ":p") on the
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	56 lines within [range] where {pattern} does NOT match.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	57
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	58 :v :vglobal
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	59 :[range]v[global]/{pattern}/[cmd]
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	60 Same as :g!.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	61
24636 840665e74421 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24103 diff changeset	62 Example: >
840665e74421 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24103 diff changeset	63 :g/^Obsolete/d _
840665e74421 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24103 diff changeset	64 Using the underscore after `:d` avoids clobbering registers or the clipboard.
840665e74421 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24103 diff changeset	65 This also makes it faster.
840665e74421 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24103 diff changeset	66
1125 96cd8222a819 updated for version 7.1a vimboss parents: 874 diff changeset	67 Instead of the '/' which surrounds the {pattern}, you can use any other
5239 11cd8d58372e Updated runtime files. Bram Moolenaar <bram@vim.org> parents: 5146 diff changeset	68 single byte character, but not an alphabetic character, '\', '"' or '\|'.
1125 96cd8222a819 updated for version 7.1a vimboss parents: 874 diff changeset	69 This is useful if you want to include a '/' in the search pattern or
96cd8222a819 updated for version 7.1a vimboss parents: 874 diff changeset	70 replacement string.
96cd8222a819 updated for version 7.1a vimboss parents: 874 diff changeset	71
96cd8222a819 updated for version 7.1a vimboss parents: 874 diff changeset	72 For the definition of a pattern, see \|pattern\|.
96cd8222a819 updated for version 7.1a vimboss parents: 874 diff changeset	73
6336 4abac79c0b7a Update runtime files. Bram Moolenaar <bram@vim.org> parents: 5763 diff changeset	74 NOTE [cmd] may contain a range; see \|collapse\| and \|edit-paragraph-join\| for
4abac79c0b7a Update runtime files. Bram Moolenaar <bram@vim.org> parents: 5763 diff changeset	75 examples.
4abac79c0b7a Update runtime files. Bram Moolenaar <bram@vim.org> parents: 5763 diff changeset	76
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	77 The global commands work by first scanning through the [range] lines and
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	78 marking each line where a match occurs (for a multi-line pattern, only the
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	79 start of the match matters).
8876 47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	80 In a second scan the [cmd] is executed for each marked line, as if the cursor
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	81 was in that line. For ":v" and ":g!" the command is executed for each not
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	82 marked line. If a line is deleted its mark disappears.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	83 The default for [range] is the whole buffer (1,$). Use "CTRL-C" to interrupt
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	84 the command. If an error message is given for a line, the command for that
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	85 line is aborted and the global command continues with the next marked or
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	86 unmarked line.
18831 6848b809a26e Runtime file updates. Bram Moolenaar <Bram@vim.org> parents: 18130 diff changeset	87 E147
11494 8e5ec22db3d8 patch 8.0.0630: it is not easy to work on lines without a match Christian Brabandt <cb@256bit.org> parents: 10895 diff changeset	88 When the command is used recursively, it only works on one line. Giving a
8e5ec22db3d8 patch 8.0.0630: it is not easy to work on lines without a match Christian Brabandt <cb@256bit.org> parents: 10895 diff changeset	89 range is then not allowed. This is useful to find all lines that match a
8e5ec22db3d8 patch 8.0.0630: it is not easy to work on lines without a match Christian Brabandt <cb@256bit.org> parents: 10895 diff changeset	90 pattern and do not match another pattern: >
8e5ec22db3d8 patch 8.0.0630: it is not easy to work on lines without a match Christian Brabandt <cb@256bit.org> parents: 10895 diff changeset	91 :g/found/v/notfound/{cmd}
8e5ec22db3d8 patch 8.0.0630: it is not easy to work on lines without a match Christian Brabandt <cb@256bit.org> parents: 10895 diff changeset	92 This first finds all lines containing "found", but only executes {cmd} when
8e5ec22db3d8 patch 8.0.0630: it is not easy to work on lines without a match Christian Brabandt <cb@256bit.org> parents: 10895 diff changeset	93 there is no match for "notfound".
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	94
11494 8e5ec22db3d8 patch 8.0.0630: it is not easy to work on lines without a match Christian Brabandt <cb@256bit.org> parents: 10895 diff changeset	95 To execute a non-Ex command, you can use the `:normal` command: >
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	96 :g/pat/normal {commands}
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	97 Make sure that {commands} ends with a whole command, otherwise Vim will wait
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	98 for you to type the rest of the command for each match. The screen will not
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	99 have been updated, so you don't know what you are doing. See \|:normal\|.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	100
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	101 The undo/redo command will undo/redo the whole global command at once.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	102 The previous context mark will only be set once (with "''" you go back to
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	103 where the cursor was before the global command).
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	104
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	105 The global command sets both the last used search pattern and the last used
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	106 substitute pattern (this is vi compatible). This makes it easy to globally
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	107 replace a string:
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	108 :g/pat/s//PAT/g
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	109 This replaces all occurrences of "pat" with "PAT". The same can be done with:
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	110 :%s/pat/PAT/g
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	111 Which is two characters shorter!
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	112
1623 53938adac247 updated for version 7.2a vimboss parents: 1270 diff changeset	113 When using "global" in Ex mode, a special case is using ":visual" as a
53938adac247 updated for version 7.2a vimboss parents: 1270 diff changeset	114 command. This will move to a matching line, go to Normal mode to let you
53938adac247 updated for version 7.2a vimboss parents: 1270 diff changeset	115 execute commands there until you use \|Q\| to return to Ex mode. This will be
53938adac247 updated for version 7.2a vimboss parents: 1270 diff changeset	116 repeated for each matching line. While doing this you cannot use ":global".
53938adac247 updated for version 7.2a vimboss parents: 1270 diff changeset	117 To abort this type CTRL-C twice.
168 4d9eabb1396e updated for version 7.0051 vimboss parents: 148 diff changeset	118
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	119 ==============================================================================
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	120 3. Complex repeats complex-repeat
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	121
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	122 q recording
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	123 q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"}
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	124 (uppercase to append). The 'q' command is disabled
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	125 while executing a register, and it doesn't work inside
7233 9487ea110214 commit https://github.com/vim/vim/commit/a0ed84a26897c994512873a895b9fc54e90c6845 Christian Brabandt <cb@256bit.org> parents: 6757 diff changeset	126 a mapping and \|:normal\|.
9487ea110214 commit https://github.com/vim/vim/commit/a0ed84a26897c994512873a895b9fc54e90c6845 Christian Brabandt <cb@256bit.org> parents: 6757 diff changeset	127
9487ea110214 commit https://github.com/vim/vim/commit/a0ed84a26897c994512873a895b9fc54e90c6845 Christian Brabandt <cb@256bit.org> parents: 6757 diff changeset	128 Note: If the register being used for recording is also
9487ea110214 commit https://github.com/vim/vim/commit/a0ed84a26897c994512873a895b9fc54e90c6845 Christian Brabandt <cb@256bit.org> parents: 6757 diff changeset	129 used for \|y\| and \|p\| the result is most likely not
9487ea110214 commit https://github.com/vim/vim/commit/a0ed84a26897c994512873a895b9fc54e90c6845 Christian Brabandt <cb@256bit.org> parents: 6757 diff changeset	130 what is expected, because the put will paste the
9487ea110214 commit https://github.com/vim/vim/commit/a0ed84a26897c994512873a895b9fc54e90c6845 Christian Brabandt <cb@256bit.org> parents: 6757 diff changeset	131 recorded macro and the yank will overwrite the
16610 1eaf34420bb3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16553 diff changeset	132 recorded macro.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	133
20552 74e3316c1d5a Update runtime files Bram Moolenaar <Bram@vim.org> parents: 20241 diff changeset	134 Note: The recording happens while you type, replaying
74e3316c1d5a Update runtime files Bram Moolenaar <Bram@vim.org> parents: 20241 diff changeset	135 the register happens as if the keys come from a
74e3316c1d5a Update runtime files Bram Moolenaar <Bram@vim.org> parents: 20241 diff changeset	136 mapping. This matters, for example, for undo, which
74e3316c1d5a Update runtime files Bram Moolenaar <Bram@vim.org> parents: 20241 diff changeset	137 only syncs when commands were typed.
74e3316c1d5a Update runtime files Bram Moolenaar <Bram@vim.org> parents: 20241 diff changeset	138
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	139 q Stops recording. (Implementation note: The 'q' that
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	140 stops recording is not stored in the register, unless
16610 1eaf34420bb3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16553 diff changeset	141 it was the result of a mapping)
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	142
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	143 @
3445 2cfb68fa26cd Updated runtime files. Bram Moolenaar <bram@vim.org> parents: 2681 diff changeset	144 @{0-9a-z".=+} Execute the contents of register {0-9a-z".=+} [count]
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	145 times. Note that register '%' (name of the current
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	146 file) and '#' (name of the alternate file) cannot be
2681 85c5a72551e2 Updated runtime files. Bram Moolenaar <bram@vim.org> parents: 2577 diff changeset	147 used.
85c5a72551e2 Updated runtime files. Bram Moolenaar <bram@vim.org> parents: 2577 diff changeset	148 The register is executed like a mapping, that means
85c5a72551e2 Updated runtime files. Bram Moolenaar <bram@vim.org> parents: 2577 diff changeset	149 that the difference between 'wildchar' and 'wildcharm'
20552 74e3316c1d5a Update runtime files Bram Moolenaar <Bram@vim.org> parents: 20241 diff changeset	150 applies, and undo might not be synced in the same way.
2681 85c5a72551e2 Updated runtime files. Bram Moolenaar <bram@vim.org> parents: 2577 diff changeset	151 For "@=" you are prompted to enter an expression. The
85c5a72551e2 Updated runtime files. Bram Moolenaar <bram@vim.org> parents: 2577 diff changeset	152 result of the expression is then executed.
16610 1eaf34420bb3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16553 diff changeset	153 See also \|@:\|.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	154
168 4d9eabb1396e updated for version 7.0051 vimboss parents: 148 diff changeset	155 @@ E748
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	156 @@ Repeat the previous @{0-9a-z":*} [count] times.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	157
24636 840665e74421 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24103 diff changeset	158 :@
3445 2cfb68fa26cd Updated runtime files. Bram Moolenaar <bram@vim.org> parents: 2681 diff changeset	159 :[addr]@{0-9a-z".=+} Execute the contents of register {0-9a-z".=+} as an Ex
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	160 command. First set cursor at line [addr] (default is
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	161 current line). When the last line in the register does
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	162 not have a <CR> it will be added automatically when
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	163 the 'e' flag is present in 'cpoptions'.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	164 For ":@=" the last used expression is used. The
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	165 result of evaluating the expression is executed as an
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	166 Ex command.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	167 Mappings are not recognized in these commands.
20891 4bdc07beeadb patch 8.2.0997: cannot execute a register containing line continuation Bram Moolenaar <Bram@vim.org> parents: 20552 diff changeset	168 When the \|line-continuation\| character (\) is present
4bdc07beeadb patch 8.2.0997: cannot execute a register containing line continuation Bram Moolenaar <Bram@vim.org> parents: 20552 diff changeset	169 at the beginning of a line in a linewise register,
4bdc07beeadb patch 8.2.0997: cannot execute a register containing line continuation Bram Moolenaar <Bram@vim.org> parents: 20552 diff changeset	170 then it is combined with the previous line. This is
4bdc07beeadb patch 8.2.0997: cannot execute a register containing line continuation Bram Moolenaar <Bram@vim.org> parents: 20552 diff changeset	171 useful for yanking and executing parts of a Vim
4bdc07beeadb patch 8.2.0997: cannot execute a register containing line continuation Bram Moolenaar <Bram@vim.org> parents: 20552 diff changeset	172 script.
16610 1eaf34420bb3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16553 diff changeset	173 Future: Will execute the register for each line in the
1eaf34420bb3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16553 diff changeset	174 address range.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	175
24636 840665e74421 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24103 diff changeset	176 :[addr]{0-9a-z".=+} :star-compatible*
840665e74421 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24103 diff changeset	177 When '*' is present in 'cpoptions' \|cpo-star\|, use
840665e74421 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24103 diff changeset	178 ":*" in the same way as ":@". This is NOT the default
840665e74421 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24103 diff changeset	179 when 'nocompatible' is used. When the '*' flag is not
840665e74421 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24103 diff changeset	180 present in 'cpoptions', ":*" is an alias for ":'<,'>",
840665e74421 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24103 diff changeset	181 select the Visual area \|:star\|.
840665e74421 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24103 diff changeset	182
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	183 :@:
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	184 :[addr]@: Repeat last command-line. First set cursor at line
16553 0e473e9e70c2 patch 8.1.1280: remarks about functionality not in Vi clutters the help Bram Moolenaar <Bram@vim.org> parents: 16267 diff changeset	185 [addr] (default is current line).
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	186
10186 a5ef9968638c commit https://github.com/vim/vim/commit/7e1479b86c590a66b63a274c079b7f18907d45a4 Christian Brabandt <cb@256bit.org> parents: 9644 diff changeset	187 :[addr]@ :@@
20241 56265f711890 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 18972 diff changeset	188 :[addr]@@ Repeat the previous :@{register}. First set cursor at
16553 0e473e9e70c2 patch 8.1.1280: remarks about functionality not in Vi clutters the help Bram Moolenaar <Bram@vim.org> parents: 16267 diff changeset	189 line [addr] (default is current line).
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	190
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	191 ==============================================================================
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	192 4. Using Vim scripts using-scripts
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	193
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	194 For writing a Vim script, see chapter 41 of the user manual \|usr_41.txt\|.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	195
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	196 :so :source load-vim-script
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	197 :so[urce] {file} Read Ex commands from {file}. These are commands that
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	198 start with a ":".
716 8ae24f338cab updated for version 7.0217 vimboss parents: 364 diff changeset	199 Triggers the \|SourcePre\| autocommand.
29236 0eef32b4ebbc Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28379 diff changeset	200 :source-range
28164 b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	201 :[range]so[urce] [++clear]
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	202 Read Ex commands from the [range] of lines in the
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	203 current buffer.
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	204
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	205 When sourcing commands from the current buffer, the
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	206 same script-ID \|<SID>\| is used even if the buffer is
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	207 sourced multiple times. If a buffer is sourced more
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	208 than once, then the functions in the buffer are
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	209 defined again.
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	210
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	211 To source a range of lines that doesn't start with the
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	212 \|:vim9script\| command in Vim9 script context, the
28246 e3d6184b89fa Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28164 diff changeset	213 \|:vim9cmd\| modifier can be used. If you use a Visual
e3d6184b89fa Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28164 diff changeset	214 selection and type ":", the range in the form "'<,'>"
e3d6184b89fa Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28164 diff changeset	215 can come before it: >
e3d6184b89fa Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28164 diff changeset	216 :'<,'>vim9cmd source
e3d6184b89fa Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28164 diff changeset	217 < Otherwise the range goes after the modifier and must
e3d6184b89fa Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28164 diff changeset	218 have a colon prefixed, like all Vim9 ranges: >
e3d6184b89fa Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28164 diff changeset	219 :vim9cmd :5,9source
28164 b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	220
28246 e3d6184b89fa Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28164 diff changeset	221 < When a range of lines in a buffer is sourced in the
28164 b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	222 Vim9 script context, the previously defined
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	223 script-local variables and functions are not cleared.
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	224 This works like the range started with the
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	225 ":vim9script noclear" command. The "++clear" argument
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	226 can be used to clear the script-local variables and
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	227 functions before sourcing the script. This works like
28246 e3d6184b89fa Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28164 diff changeset	228 the range started with the `:vim9script` command
28164 b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	229 without the "noclear" argument. See \|vim9-reload\| for
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	230 more information.
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	231 Examples: >
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	232 :4,5source
b0b712d48225 patch 8.2.4607: sourcing buffer lines may lead to errors for conflicts Bram Moolenaar <Bram@vim.org> parents: 28158 diff changeset	233 :10,18source ++clear
28139 f34afadbef47 patch 8.2.4594: need to write script to a file to be able to source them Bram Moolenaar <Bram@vim.org> parents: 27321 diff changeset	234
16808 c002c4899529 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 16610 diff changeset	235 :source!
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	236 :so[urce]! {file} Read Vim commands from {file}. These are commands
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	237 that are executed from Normal mode, like you type
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	238 them.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	239 When used after \|:global\|, \|:argdo\|, \|:windo\|,
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	240 \|:bufdo\|, in a loop or when another command follows
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	241 the display won't be updated while executing the
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	242 commands.
16808 c002c4899529 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 16610 diff changeset	243 Cannot be used in the \|sandbox\|.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	244
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	245 :ru :runtime
8526 981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	246 :ru[ntime][!] [where] {file} ..
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	247 Read Ex commands from {file} in each directory given
8526 981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	248 by 'runtimepath' and/or 'packpath'. There is no error
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	249 for non-existing files.
18831 6848b809a26e Runtime file updates. Bram Moolenaar <Bram@vim.org> parents: 18130 diff changeset	250
8526 981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	251 Example: >
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	252 :runtime syntax/c.vim
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	253
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	254 < There can be multiple {file} arguments, separated by
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	255 spaces. Each {file} is searched for in the first
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	256 directory from 'runtimepath', then in the second
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	257 directory, etc. Use a backslash to include a space
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	258 inside {file} (although it's better not to use spaces
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	259 in file names, it causes trouble).
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	260
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	261 When [!] is included, all found files are sourced.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	262 When it is not included only the first found file is
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	263 sourced.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	264
8526 981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	265 When [where] is omitted only 'runtimepath' is used.
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	266 Other values:
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	267 START search under "start" in 'packpath'
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	268 OPT search under "opt" in 'packpath'
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	269 PACK search under "start" and "opt" in
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	270 'packpath'
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	271 ALL first use 'runtimepath', then search
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	272 under "start" and "opt" in 'packpath'
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	273
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	274 When {file} contains wildcards it is expanded to all
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	275 matching files. Example: >
18130 1e5672da6a69 Updte runtime files Bram Moolenaar <Bram@vim.org> parents: 17161 diff changeset	276 :runtime! plugin/*/.vim
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	277 < This is what Vim uses to load the plugin files when
237 73354c21f1e4 updated for version 7.0066 vimboss parents: 177 diff changeset	278 starting up. This similar command: >
18130 1e5672da6a69 Updte runtime files Bram Moolenaar <Bram@vim.org> parents: 17161 diff changeset	279 :runtime plugin/*/.vim
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	280 < would source the first file only.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	281
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	282 When 'verbose' is one or higher, there is a message
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	283 when no file could be found.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	284 When 'verbose' is two or higher, there is a message
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	285 about each searched file.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	286
8416 1a6527cce675 commit https://github.com/vim/vim/commit/be82c254862e475a582c0717455e1db6bf96b0d0 Christian Brabandt <cb@256bit.org> parents: 8392 diff changeset	287 :pa :packadd E919
8392 1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	288 :pa[ckadd][!] {name} Search for an optional plugin directory in 'packpath'
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	289 and source any plugin files found. The directory must
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	290 match:
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	291 pack/*/opt/{name} ~
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	292 The directory is added to 'runtimepath' if it wasn't
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	293 there yet.
9116 bc38030aec7d commit https://github.com/vim/vim/commit/26852128a2b713ef49341a0c18daba928444e7eb Christian Brabandt <cb@256bit.org> parents: 8876 diff changeset	294 If the directory pack/*/opt/{name}/after exists it is
bc38030aec7d commit https://github.com/vim/vim/commit/26852128a2b713ef49341a0c18daba928444e7eb Christian Brabandt <cb@256bit.org> parents: 8876 diff changeset	295 added at the end of 'runtimepath'.
8303 88207f4b861a commit https://github.com/vim/vim/commit/dae8d21dd291df6a6679a00be64e18bca0156576 Christian Brabandt <cb@256bit.org> parents: 8246 diff changeset	296
13051 a6d3e2081544 Update runtime files Christian Brabandt <cb@256bit.org> parents: 11494 diff changeset	297 If loading packages from "pack/*/start" was skipped,
a6d3e2081544 Update runtime files Christian Brabandt <cb@256bit.org> parents: 11494 diff changeset	298 then this directory is searched first:
a6d3e2081544 Update runtime files Christian Brabandt <cb@256bit.org> parents: 11494 diff changeset	299 pack/*/start/{name} ~
a6d3e2081544 Update runtime files Christian Brabandt <cb@256bit.org> parents: 11494 diff changeset	300
8182 95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	301 Note that {name} is the directory name, not the name
8876 47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	302 of the .vim file. All the files matching the pattern
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	303 pack//opt/{name}/plugin//.vim ~
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	304 will be sourced. This allows for using subdirectories
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	305 below "plugin", just like with plugins in
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	306 'runtimepath'.
8182 95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	307
8392 1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	308 If the filetype detection was not enabled yet (this
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	309 is usually done with a "syntax enable" or "filetype
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	310 on" command in your .vimrc file), this will also look
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	311 for "{name}/ftdetect/*.vim" files.
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	312
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	313 When the optional ! is added no plugin files or
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	314 ftdetect scripts are loaded, only the matching
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	315 directories are added to 'runtimepath'. This is
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	316 useful in your .vimrc. The plugins will then be
24911 fd37be6dc258 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24636 diff changeset	317 loaded during initialization, see \|load-plugins\| (note
fd37be6dc258 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24636 diff changeset	318 that the loading order will be reversed, because each
fd37be6dc258 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24636 diff changeset	319 directory is inserted before others).
22565 17c4178f26ea Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 21825 diff changeset	320 Note that for ftdetect scripts to be loaded
17c4178f26ea Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 21825 diff changeset	321 you will need to write `filetype plugin indent on`
17c4178f26ea Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 21825 diff changeset	322 AFTER all `packadd!` commands.
8392 1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	323
1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	324 Also see \|pack-add\|.
14249 4543777545a3 Updated runtime and language files. Christian Brabandt <cb@256bit.org> parents: 13963 diff changeset	325 {only available when compiled with \|+eval\|}
8392 1bf1b88968a2 commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69 Christian Brabandt <cb@256bit.org> parents: 8388 diff changeset	326
8673 ed7251c3e2d3 commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07 Christian Brabandt <cb@256bit.org> parents: 8526 diff changeset	327 :packl :packloadall
8876 47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	328 :packl[oadall][!] Load all packages in the "start" directory under each
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	329 entry in 'packpath'.
18831 6848b809a26e Runtime file updates. Bram Moolenaar <Bram@vim.org> parents: 18130 diff changeset	330
8876 47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	331 First all the directories found are added to
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	332 'runtimepath', then the plugins found in the
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	333 directories are sourced. This allows for a plugin to
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	334 depend on something of another plugin, e.g. an
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	335 "autoload" directory. See \|packload-two-steps\| for
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	336 how this can be useful.
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	337
8673 ed7251c3e2d3 commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07 Christian Brabandt <cb@256bit.org> parents: 8526 diff changeset	338 This is normally done automatically during startup,
ed7251c3e2d3 commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07 Christian Brabandt <cb@256bit.org> parents: 8526 diff changeset	339 after loading your .vimrc file. With this command it
ed7251c3e2d3 commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07 Christian Brabandt <cb@256bit.org> parents: 8526 diff changeset	340 can be done earlier.
8876 47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	341
17161 9ccb1ea9b2fc Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16808 diff changeset	342 Packages will be loaded only once. Using
9ccb1ea9b2fc Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16808 diff changeset	343 `:packloadall` a second time will have no effect.
9ccb1ea9b2fc Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16808 diff changeset	344 When the optional ! is added this command will load
9ccb1ea9b2fc Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16808 diff changeset	345 packages even when done before.
9ccb1ea9b2fc Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16808 diff changeset	346
9ccb1ea9b2fc Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16808 diff changeset	347 Note that when using `:packloadall` in the \|vimrc\|
9ccb1ea9b2fc Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16808 diff changeset	348 file, the 'runtimepath' option is updated, and later
9ccb1ea9b2fc Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16808 diff changeset	349 all plugins in 'runtimepath' will be loaded, which
9ccb1ea9b2fc Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16808 diff changeset	350 means they are loaded again. Plugins are expected to
9ccb1ea9b2fc Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16808 diff changeset	351 handle that.
8876 47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	352
8795 aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354 Christian Brabandt <cb@256bit.org> parents: 8748 diff changeset	353 An error only causes sourcing the script where it
8673 ed7251c3e2d3 commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07 Christian Brabandt <cb@256bit.org> parents: 8526 diff changeset	354 happens to be aborted, further plugins will be loaded.
8526 981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	355 See \|packages\|.
14249 4543777545a3 Updated runtime and language files. Christian Brabandt <cb@256bit.org> parents: 13963 diff changeset	356 {only available when compiled with \|+eval\|}
8182 95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	357
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	358 :scripte[ncoding] [encoding] :scripte :scriptencoding E167
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	359 Specify the character encoding used in the script.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	360 The following lines will be converted from [encoding]
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	361 to the value of the 'encoding' option, if they are
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	362 different. Examples: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	363 scriptencoding iso-8859-5
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	364 scriptencoding cp932
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	365 <
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	366 When [encoding] is empty, no conversion is done. This
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	367 can be used to restrict conversion to a sequence of
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	368 lines: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	369 scriptencoding euc-jp
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	370 ... lines to be converted ...
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	371 scriptencoding
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	372 ... not converted ...
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	373
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	374 < When conversion isn't supported by the system, there
9644 9f7bcc2c3b97 commit https://github.com/vim/vim/commit/6f1d9a096bf22d50c727dca73abbfb8e3ff55176 Christian Brabandt <cb@256bit.org> parents: 9286 diff changeset	375 is no error message and no conversion is done. When a
9f7bcc2c3b97 commit https://github.com/vim/vim/commit/6f1d9a096bf22d50c727dca73abbfb8e3ff55176 Christian Brabandt <cb@256bit.org> parents: 9286 diff changeset	376 line can't be converted there is no error and the
9f7bcc2c3b97 commit https://github.com/vim/vim/commit/6f1d9a096bf22d50c727dca73abbfb8e3ff55176 Christian Brabandt <cb@256bit.org> parents: 9286 diff changeset	377 original line is kept.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	378
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	379 Don't use "ucs-2" or "ucs-4", scripts cannot be in
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	380 these encodings (they would contain NUL bytes).
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	381 When a sourced script starts with a BOM (Byte Order
2207 b17bbfa96fa0 Add the settabvar() and gettabvar() functions. Bram Moolenaar <bram@vim.org> parents: 2154 diff changeset	382 Mark) in utf-8 format Vim will recognize it, no need
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	383 to use ":scriptencoding utf-8" then.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	384
10895 c391bfbdb452 Updated runtime files. Christian Brabandt <cb@256bit.org> parents: 10198 diff changeset	385 If you set the 'encoding' option in your \|.vimrc\|,
c391bfbdb452 Updated runtime files. Christian Brabandt <cb@256bit.org> parents: 10198 diff changeset	386 `:scriptencoding` must be placed after that. E.g.: >
c391bfbdb452 Updated runtime files. Christian Brabandt <cb@256bit.org> parents: 10198 diff changeset	387 set encoding=utf-8
c391bfbdb452 Updated runtime files. Christian Brabandt <cb@256bit.org> parents: 10198 diff changeset	388 scriptencoding utf-8
c391bfbdb452 Updated runtime files. Christian Brabandt <cb@256bit.org> parents: 10198 diff changeset	389 <
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	390
16223 abb67309c1ca patch 8.1.1116: cannot enforce a Vim script style Bram Moolenaar <Bram@vim.org> parents: 15878 diff changeset	391 :scriptv[ersion] {version} :scriptv :scriptversion
27321 3649b5a6b1b6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 27215 diff changeset	392 E999 E984 E1040
16267 b471858040bc Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 16223 diff changeset	393 Specify the version of Vim for the lines that follow
b471858040bc Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 16223 diff changeset	394 in the same file. Only applies at the toplevel of
b471858040bc Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 16223 diff changeset	395 sourced scripts, not inside functions.
16223 abb67309c1ca patch 8.1.1116: cannot enforce a Vim script style Bram Moolenaar <Bram@vim.org> parents: 15878 diff changeset	396
abb67309c1ca patch 8.1.1116: cannot enforce a Vim script style Bram Moolenaar <Bram@vim.org> parents: 15878 diff changeset	397 If {version} is higher than what the current Vim
abb67309c1ca patch 8.1.1116: cannot enforce a Vim script style Bram Moolenaar <Bram@vim.org> parents: 15878 diff changeset	398 version supports E999 will be given. You either need
abb67309c1ca patch 8.1.1116: cannot enforce a Vim script style Bram Moolenaar <Bram@vim.org> parents: 15878 diff changeset	399 to rewrite the script to make it work with an older
abb67309c1ca patch 8.1.1116: cannot enforce a Vim script style Bram Moolenaar <Bram@vim.org> parents: 15878 diff changeset	400 Vim version, or update Vim to a newer version. See
abb67309c1ca patch 8.1.1116: cannot enforce a Vim script style Bram Moolenaar <Bram@vim.org> parents: 15878 diff changeset	401 \|vimscript-version\| for what changed between versions.
abb67309c1ca patch 8.1.1116: cannot enforce a Vim script style Bram Moolenaar <Bram@vim.org> parents: 15878 diff changeset	402
27215 5b54f413d132 patch 8.2.4136: Vim9: the "autoload" argument of ":vim9script" is not useful Bram Moolenaar <Bram@vim.org> parents: 27213 diff changeset	403 :vim9s[cript] [noclear] :vim9s :vim9script
23466 15fa3923cc49 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 22565 diff changeset	404 Marks a script file as containing \|Vim9-script\|
27321 3649b5a6b1b6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 27215 diff changeset	405 commands. Also see \|vim9-namespace\|. E1038
3649b5a6b1b6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 27215 diff changeset	406 Must be the first command in the file. E1039
23466 15fa3923cc49 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 22565 diff changeset	407 For [noclear] see \|vim9-reload\|.
15fa3923cc49 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 22565 diff changeset	408 Without the \|+eval\| feature this changes the syntax
15fa3923cc49 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 22565 diff changeset	409 for some commands.
23938 2a885d095bff patch 8.2.2511: Vim9: cannot use Vim9 script syntax in some places Bram Moolenaar <Bram@vim.org> parents: 23717 diff changeset	410 See \|:vim9cmd\| for executing one command with Vim9
2a885d095bff patch 8.2.2511: Vim9: cannot use Vim9 script syntax in some places Bram Moolenaar <Bram@vim.org> parents: 23717 diff changeset	411 syntax and semantics.
24911 fd37be6dc258 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24636 diff changeset	412
6476 11d78e58a487 Update runtime files. Bram Moolenaar <bram@vim.org> parents: 6336 diff changeset	413 :scr :scriptnames
11d78e58a487 Update runtime files. Bram Moolenaar <bram@vim.org> parents: 6336 diff changeset	414 :scr[iptnames] List all sourced script names, in the order they were
27215 5b54f413d132 patch 8.2.4136: Vim9: the "autoload" argument of ":vim9script" is not useful Bram Moolenaar <Bram@vim.org> parents: 27213 diff changeset	415 first encountered. The number is used for the script
5b54f413d132 patch 8.2.4136: Vim9: the "autoload" argument of ":vim9script" is not useful Bram Moolenaar <Bram@vim.org> parents: 27213 diff changeset	416 ID \|<SID>\|.
27213 42561e956a70 patch 8.2.4135: Vim9: ":scriptnames" shows unloaded imported autoload script Bram Moolenaar <Bram@vim.org> parents: 27162 diff changeset	417 For a script that was used with `import autoload` but
42561e956a70 patch 8.2.4135: Vim9: ":scriptnames" shows unloaded imported autoload script Bram Moolenaar <Bram@vim.org> parents: 27162 diff changeset	418 was not actually sourced yet an "A" is shown after the
42561e956a70 patch 8.2.4135: Vim9: ":scriptnames" shows unloaded imported autoload script Bram Moolenaar <Bram@vim.org> parents: 27162 diff changeset	419 script ID.
16553 0e473e9e70c2 patch 8.1.1280: remarks about functionality not in Vi clutters the help Bram Moolenaar <Bram@vim.org> parents: 16267 diff changeset	420 {not available when compiled without the \|+eval\|
0e473e9e70c2 patch 8.1.1280: remarks about functionality not in Vi clutters the help Bram Moolenaar <Bram@vim.org> parents: 16267 diff changeset	421 feature}
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	422
15085 1783c0b6bc2e patch 8.1.0553: it is not easy to edit a script that was sourced Bram Moolenaar <Bram@vim.org> parents: 14864 diff changeset	423 :scr[iptnames][!] {scriptId} :script
15194 8b334e4cb97f Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15085 diff changeset	424 Edit script {scriptId}. Although ":scriptnames name"
8b334e4cb97f Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15085 diff changeset	425 works, using ":script name" is recommended.
8b334e4cb97f Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15085 diff changeset	426 When the current buffer can't be \|abandon\|ed and the !
8b334e4cb97f Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15085 diff changeset	427 is not present, the command fails.
15085 1783c0b6bc2e patch 8.1.0553: it is not easy to edit a script that was sourced Bram Moolenaar <Bram@vim.org> parents: 14864 diff changeset	428
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	429 :fini :finish E168
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	430 :fini[sh] Stop sourcing a script. Can only be used in a Vim
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	431 script file. This is a quick way to skip the rest of
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	432 the file. If it is used after a \|:try\| but before the
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	433 matching \|:finally\| (if present), the commands
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	434 following the ":finally" up to the matching \|:endtry\|
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	435 are executed first. This process applies to all
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	436 nested ":try"s in the script. The outermost ":endtry"
16553 0e473e9e70c2 patch 8.1.1280: remarks about functionality not in Vi clutters the help Bram Moolenaar <Bram@vim.org> parents: 16267 diff changeset	437 then stops sourcing the script.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	438
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	439 All commands and command sequences can be repeated by putting them in a named
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	440 register and then executing it. There are two ways to get the commands in the
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	441 register:
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	442 - Use the record command "q". You type the commands once, and while they are
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	443 being executed they are stored in a register. Easy, because you can see
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	444 what you are doing. If you make a mistake, "p"ut the register into the
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	445 file, edit the command sequence, and then delete it into the register
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	446 again. You can continue recording by appending to the register (use an
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	447 uppercase letter).
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	448 - Delete or yank the command sequence into the register.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	449
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	450 Often used command sequences can be put under a function key with the ':map'
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	451 command.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	452
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	453 An alternative is to put the commands in a file, and execute them with the
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	454 ':source!' command. Useful for long command sequences. Can be combined with
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	455 the ':map' command to put complicated commands under a function key.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	456
28158 e1d1fa6ba1ed patch 8.2.4603: sourcing buffer lines is too complicated Bram Moolenaar <Bram@vim.org> parents: 28139 diff changeset	457 The ':source' command reads Ex commands from a file or a buffer line by line.
e1d1fa6ba1ed patch 8.2.4603: sourcing buffer lines is too complicated Bram Moolenaar <Bram@vim.org> parents: 28139 diff changeset	458 You will have to type any needed keyboard input. The ':source!' command reads
e1d1fa6ba1ed patch 8.2.4603: sourcing buffer lines is too complicated Bram Moolenaar <Bram@vim.org> parents: 28139 diff changeset	459 from a script file character by character, interpreting each character as if
e1d1fa6ba1ed patch 8.2.4603: sourcing buffer lines is too complicated Bram Moolenaar <Bram@vim.org> parents: 28139 diff changeset	460 you typed it.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	461
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	462 Example: When you give the ":!ls" command you get the \|hit-enter\| prompt. If
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	463 you ':source' a file with the line "!ls" in it, you will have to type the
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	464 <Enter> yourself. But if you ':source!' a file with the line ":!ls" in it,
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	465 the next characters from that file are read until a <CR> is found. You will
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	466 not have to type <CR> yourself, unless ":!ls" was the last line in the file.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	467
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	468 It is possible to put ':source[!]' commands in the script file, so you can
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	469 make a top-down hierarchy of script files. The ':source' command can be
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	470 nested as deep as the number of files that can be opened at one time (about
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	471 15). The ':source!' command can be nested up to 15 levels deep.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	472
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	473 You can use the "<sfile>" string (literally, this is not a special key) inside
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	474 of the sourced file, in places where a file name is expected. It will be
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	475 replaced by the file name of the sourced file. For example, if you have a
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	476 "other.vimrc" file in the same directory as your ".vimrc" file, you can source
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	477 it from your ".vimrc" file with this command: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	478 :source <sfile>:h/other.vimrc
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	479
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	480 In script files terminal-dependent key codes are represented by
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	481 terminal-independent two character codes. This means that they can be used
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	482 in the same way on different kinds of terminals. The first character of a
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	483 key code is 0x80 or 128, shown on the screen as "~@". The second one can be
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	484 found in the list \|key-notation\|. Any of these codes can also be entered
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	485 with CTRL-V followed by the three digit decimal code. This does NOT work for
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	486 the <t_xx> termcap codes, these can only be used in mappings.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	487
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	488 :source_crnl W15
18912 ccd16426a1f9 patch 8.2.0017: OS/2 and MS-DOS are still mentioned Bram Moolenaar <Bram@vim.org> parents: 18879 diff changeset	489 Win32: Files that are read with ":source" normally have <CR><NL> <EOL>s.
ccd16426a1f9 patch 8.2.0017: OS/2 and MS-DOS are still mentioned Bram Moolenaar <Bram@vim.org> parents: 18879 diff changeset	490 These always work. If you are using a file with <NL> <EOL>s (for example, a
ccd16426a1f9 patch 8.2.0017: OS/2 and MS-DOS are still mentioned Bram Moolenaar <Bram@vim.org> parents: 18879 diff changeset	491 file made on Unix), this will be recognized if 'fileformats' is not empty and
ccd16426a1f9 patch 8.2.0017: OS/2 and MS-DOS are still mentioned Bram Moolenaar <Bram@vim.org> parents: 18879 diff changeset	492 the first line does not end in a <CR>. This fails if the first line has
ccd16426a1f9 patch 8.2.0017: OS/2 and MS-DOS are still mentioned Bram Moolenaar <Bram@vim.org> parents: 18879 diff changeset	493 something like ":map <F1> :help^M", where "^M" is a <CR>. If the first line
ccd16426a1f9 patch 8.2.0017: OS/2 and MS-DOS are still mentioned Bram Moolenaar <Bram@vim.org> parents: 18879 diff changeset	494 ends in a <CR>, but following ones don't, you will get an error message,
ccd16426a1f9 patch 8.2.0017: OS/2 and MS-DOS are still mentioned Bram Moolenaar <Bram@vim.org> parents: 18879 diff changeset	495 because the <CR> from the first lines will be lost.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	496
333 18f024844150 updated for version 7.0086 vimboss parents: 237 diff changeset	497 Mac Classic: Files that are read with ":source" normally have <CR> <EOL>s.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	498 These always work. If you are using a file with <NL> <EOL>s (for example, a
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	499 file made on Unix), this will be recognized if 'fileformats' is not empty and
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	500 the first line does not end in a <CR>. Be careful not to use a file with <NL>
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	501 linebreaks which has a <CR> in first line.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	502
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	503 On other systems, Vim expects ":source"ed files to end in a <NL>. These
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	504 always work. If you are using a file with <CR><NL> <EOL>s (for example, a
18972 130acb903dbe Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 18912 diff changeset	505 file made on MS-Windows), all lines will have a trailing <CR>. This may cause
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	506 problems for some commands (e.g., mappings). There is no automatic <EOL>
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	507 detection, because it's common to start with a line that defines a mapping
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	508 that ends in a <CR>, which will confuse the automaton.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	509
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	510 line-continuation
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	511 Long lines in a ":source"d Ex command script file can be split by inserting
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	512 a line continuation symbol "\" (backslash) at the start of the next line.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	513 There can be white space before the backslash, which is ignored.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	514
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	515 Example: the lines >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	516 :set comments=sr:/,mb:,el:*/,
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	517 \://,
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	518 \b:#,
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	519 \:%,
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	520 \n:>,
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	521 \fb:-
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	522 are interpreted as if they were given in one line:
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	523 :set comments=sr:/,mb:,el:*/,://,b:#,:%,n:>,fb:-
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	524
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	525 All leading whitespace characters in the line before a backslash are ignored.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	526 Note however that trailing whitespace in the line before it cannot be
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	527 inserted freely; it depends on the position where a command is split up
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	528 whether additional whitespace is allowed or not.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	529
2033 de5a43c5eedc Update documentation files. Bram Moolenaar <bram@zimbu.org> parents: 1702 diff changeset	530 When a space is required it's best to put it right after the backslash. A
de5a43c5eedc Update documentation files. Bram Moolenaar <bram@zimbu.org> parents: 1702 diff changeset	531 space at the end of a line is hard to see and may be accidentally deleted. >
de5a43c5eedc Update documentation files. Bram Moolenaar <bram@zimbu.org> parents: 1702 diff changeset	532 :syn match Comment
de5a43c5eedc Update documentation files. Bram Moolenaar <bram@zimbu.org> parents: 1702 diff changeset	533 \ "very long regexp"
de5a43c5eedc Update documentation files. Bram Moolenaar <bram@zimbu.org> parents: 1702 diff changeset	534 \ keepend
de5a43c5eedc Update documentation files. Bram Moolenaar <bram@zimbu.org> parents: 1702 diff changeset	535
26779 edb7d53fc7e3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 26304 diff changeset	536 In \|Vim9\| script the backslash can often be omitted, but not always.
edb7d53fc7e3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 26304 diff changeset	537 See \|vim9-line-continuation\|.
edb7d53fc7e3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 26304 diff changeset	538
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	539 There is a problem with the ":append" and ":insert" commands: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	540 :1append
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	541 \asdf
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	542 .
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	543 The backslash is seen as a line-continuation symbol, thus this results in the
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	544 command: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	545 :1appendasdf
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	546 .
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	547 To avoid this, add the 'C' flag to the 'cpoptions' option: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	548 :set cpo+=C
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	549 :1append
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	550 \asdf
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	551 .
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	552 :set cpo-=C
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	553
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	554 Note that when the commands are inside a function, you need to add the 'C'
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	555 flag when defining the function, it is not relevant when executing it. >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	556 :set cpo+=C
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	557 :function Foo()
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	558 :1append
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	559 \asdf
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	560 .
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	561 :endfunction
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	562 :set cpo-=C
14714 bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	563 <
bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	564 line-continuation-comment
14864 40ef13331e02 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 14714 diff changeset	565 To add a comment in between the lines start with '"\ '. Notice the space
40ef13331e02 Update runtime files. Christian Brabandt <cb@256bit.org> parents: 14714 diff changeset	566 after the backslash. Example: >
14714 bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	567 let array = [
bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	568 "\ first entry comment
bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	569 \ 'first',
bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	570 "\ second entry comment
bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	571 \ 'second',
bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	572 \ ]
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	573
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	574 Rationale:
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	575 Most programs work with a trailing backslash to indicate line
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	576 continuation. Using this in Vim would cause incompatibility with Vi.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	577 For example for this Vi mapping: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	578 :map xx asdf\
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	579 < Therefore the unusual leading backslash is used.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	580
14714 bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	581 Starting a comment in a continuation line results in all following
bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	582 continuation lines to be part of the comment. Since it was like this
bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	583 for a long time, when making it possible to add a comment halfway a
bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	584 sequence of continuation lines, it was not possible to use \", since
bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	585 that was a valid continuation line. Using '"\ ' comes closest, even
bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	586 though it may look a bit weird. Requiring the space after the
bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	587 backslash is to make it very unlikely this is a normal comment line.
bdbb049c2aa8 patch 8.1.0369: continuation lines cannot contain comments Christian Brabandt <cb@256bit.org> parents: 14421 diff changeset	588
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	589 ==============================================================================
8182 95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	590 5. Using Vim packages packages
95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	591
95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	592 A Vim package is a directory that contains one or more plugins. The
95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	593 advantages over normal plugins:
95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	594 - A package can be downloaded as an archive and unpacked in its own directory.
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	595 Thus the files are not mixed with files of other plugins. That makes it
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	596 easy to update and remove.
8376 e448f2a5d45b commit https://github.com/vim/vim/commit/91715873d19a1859c08eeded7848113596e2f2bd Christian Brabandt <cb@256bit.org> parents: 8303 diff changeset	597 - A package can be a git, mercurial, etc. repository. That makes it really
8182 95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	598 easy to update.
95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	599 - A package can contain multiple plugins that depend on each other.
95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	600 - A package can contain plugins that are automatically loaded on startup and
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	601 ones that are only loaded when needed with `:packadd`.
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	602
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	603
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	604 Using a package and loading automatically ~
8182 95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	605
95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	606 Let's assume your Vim files are in the "~/.vim" directory and you want to add a
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	607 package from a zip archive "/tmp/foopack.zip":
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	608 % mkdir -p ~/.vim/pack/foo
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	609 % cd ~/.vim/pack/foo
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	610 % unzip /tmp/foopack.zip
8182 95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	611
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	612 The directory name "foo" is arbitrary, you can pick anything you like.
8182 95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	613
95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	614 You would now have these files under ~/.vim:
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	615 pack/foo/README.txt
8475 aec051e61547 commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	616 pack/foo/start/foobar/plugin/foo.vim
aec051e61547 commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	617 pack/foo/start/foobar/syntax/some.vim
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	618 pack/foo/opt/foodebug/plugin/debugger.vim
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	619
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	620 When Vim starts up, after processing your .vimrc, it scans all directories in
8876 47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	621 'packpath' for plugins under the "pack/*/start" directory. First all those
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	622 directories are added to 'runtimepath'. Then all the plugins are loaded.
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	623 See \|packload-two-steps\| for how these two steps can be useful.
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	624
18831 6848b809a26e Runtime file updates. Bram Moolenaar <Bram@vim.org> parents: 18130 diff changeset	625 In the example Vim will find "pack/foo/start/foobar/plugin/foo.vim" and adds
8475 aec051e61547 commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	626 "~/.vim/pack/foo/start/foobar" to 'runtimepath'.
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	627
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	628 If the "foobar" plugin kicks in and sets the 'filetype' to "some", Vim will
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	629 find the syntax/some.vim file, because its directory is in 'runtimepath'.
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	630
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	631 Vim will also load ftdetect files, if there are any.
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	632
8748 b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	633 Note that the files under "pack/foo/opt" are not loaded automatically, only the
8475 aec051e61547 commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	634 ones under "pack/foo/start". See \|pack-add\| below for how the "opt" directory
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	635 is used.
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	636
8526 981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	637 Loading packages automatically will not happen if loading plugins is disabled,
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	638 see \|load-plugins\|.
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	639
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	640 To load packages earlier, so that 'runtimepath' gets updated: >
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	641 :packloadall
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	642 This also works when loading plugins is disabled. The automatic loading will
981cc3bef9f3 commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9 Christian Brabandt <cb@256bit.org> parents: 8475 diff changeset	643 only happen once.
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	644
9116 bc38030aec7d commit https://github.com/vim/vim/commit/26852128a2b713ef49341a0c18daba928444e7eb Christian Brabandt <cb@256bit.org> parents: 8876 diff changeset	645 If the package has an "after" directory, that directory is added to the end of
bc38030aec7d commit https://github.com/vim/vim/commit/26852128a2b713ef49341a0c18daba928444e7eb Christian Brabandt <cb@256bit.org> parents: 8876 diff changeset	646 'runtimepath', so that anything there will be loaded later.
bc38030aec7d commit https://github.com/vim/vim/commit/26852128a2b713ef49341a0c18daba928444e7eb Christian Brabandt <cb@256bit.org> parents: 8876 diff changeset	647
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	648
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	649 Using a single plugin and loading it automatically ~
8182 95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	650
8388 f5972de59001 commit https://github.com/vim/vim/commit/f3654827368e6204608036353a0360e9e7c21e02 Christian Brabandt <cb@256bit.org> parents: 8376 diff changeset	651 If you don't have a package but a single plugin, you need to create the extra
f5972de59001 commit https://github.com/vim/vim/commit/f3654827368e6204608036353a0360e9e7c21e02 Christian Brabandt <cb@256bit.org> parents: 8376 diff changeset	652 directory level:
8475 aec051e61547 commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	653 % mkdir -p ~/.vim/pack/foo/start/foobar
aec051e61547 commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	654 % cd ~/.vim/pack/foo/start/foobar
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	655 % unzip /tmp/someplugin.zip
8182 95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	656
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	657 You would now have these files:
8475 aec051e61547 commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	658 pack/foo/start/foobar/plugin/foo.vim
aec051e61547 commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43 Christian Brabandt <cb@256bit.org> parents: 8440 diff changeset	659 pack/foo/start/foobar/syntax/some.vim
8182 95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	660
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	661 From here it works like above.
8182 95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	662
8376 e448f2a5d45b commit https://github.com/vim/vim/commit/91715873d19a1859c08eeded7848113596e2f2bd Christian Brabandt <cb@256bit.org> parents: 8303 diff changeset	663
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	664 Optional plugins ~
8388 f5972de59001 commit https://github.com/vim/vim/commit/f3654827368e6204608036353a0360e9e7c21e02 Christian Brabandt <cb@256bit.org> parents: 8376 diff changeset	665 pack-add
f5972de59001 commit https://github.com/vim/vim/commit/f3654827368e6204608036353a0360e9e7c21e02 Christian Brabandt <cb@256bit.org> parents: 8376 diff changeset	666 To load an optional plugin from a pack use the `:packadd` command: >
8440 4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	667 :packadd foodebug
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	668 This searches for "pack/*/opt/foodebug" in 'packpath' and will find
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	669 ~/.vim/pack/foo/opt/foodebug/plugin/debugger.vim and source it.
4c6ad81d41fe commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7 Christian Brabandt <cb@256bit.org> parents: 8416 diff changeset	670
8748 b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	671 This could be done if some conditions are met. For example, depending on
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	672 whether Vim supports a feature or a dependency is missing.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	673
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	674 You can also load an optional plugin at startup, by putting this command in
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	675 your \|.vimrc\|: >
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	676 :packadd! foodebug
9286 64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8 Christian Brabandt <cb@256bit.org> parents: 9116 diff changeset	677 The extra "!" is so that the plugin isn't loaded if Vim was started with
8748 b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	678 \|--noplugin\|.
8182 95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	679
95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	680 It is perfectly normal for a package to only have files in the "opt"
95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	681 directory. You then need to load each plugin when you want to use it.
95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	682
8748 b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	683
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	684 Where to put what ~
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	685
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	686 Since color schemes, loaded with `:colorscheme`, are found below
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	687 "pack//start" and "pack//opt", you could put them anywhere. We recommend
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	688 you put them below "pack/*/opt", for example
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	689 ".vim/pack/mycolors/opt/dark/colors/very_dark.vim".
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	690
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	691 Filetype plugins should go under "pack/*/start", so that they are always
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	692 found. Unless you have more than one plugin for a file type and want to
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	693 select which one to load with `:packadd`. E.g. depending on the compiler
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	694 version: >
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	695 if foo_compiler_version > 34
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	696 packadd foo_new
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	697 else
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	698 packadd foo_old
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	699 endif
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	700
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	701 The "after" directory is most likely not useful in a package. It's not
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	702 disallowed though.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	703
8182 95d59081580f commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf Christian Brabandt <cb@256bit.org> parents: 8061 diff changeset	704 ==============================================================================
8748 b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	705 6. Creating Vim packages package-create
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	706
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	707 This assumes you write one or more plugins that you distribute as a package.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	708
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	709 If you have two unrelated plugins you would use two packages, so that Vim
21499 3a1ed539ae2a Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 20891 diff changeset	710 users can choose what they include or not. Or you can decide to use one
21825 0db0640e16e0 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 21499 diff changeset	711 package with optional plugins, and tell the user to add the preferred ones with
8748 b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	712 `:packadd`.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	713
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	714 Decide how you want to distribute the package. You can create an archive or
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	715 you could use a repository. An archive can be used by more users, but is a
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	716 bit harder to update to a new version. A repository can usually be kept
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	717 up-to-date easily, but it requires a program like "git" to be available.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	718 You can do both, github can automatically create an archive for a release.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	719
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	720 Your directory layout would be like this:
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	721 start/foobar/plugin/foo.vim " always loaded, defines commands
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	722 start/foobar/plugin/bar.vim " always loaded, defines commands
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	723 start/foobar/autoload/foo.vim " loaded when foo command used
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	724 start/foobar/doc/foo.txt " help for foo.vim
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	725 start/foobar/doc/tags " help tags
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	726 opt/fooextra/plugin/extra.vim " optional plugin, defines commands
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	727 opt/fooextra/autoload/extra.vim " loaded when extra command used
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	728 opt/fooextra/doc/extra.txt " help for extra.vim
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	729 opt/fooextra/doc/tags " help tags
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	730
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	731 This allows for the user to do: >
24103 788e10cec9bd Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 24024 diff changeset	732 mkdir ~/.vim/pack
788e10cec9bd Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 24024 diff changeset	733 cd ~/.vim/pack
788e10cec9bd Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 24024 diff changeset	734 git clone https://github.com/you/foobar.git myfoobar
8748 b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	735
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	736 Here "myfoobar" is a name that the user can choose, the only condition is that
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	737 it differs from other packages.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	738
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	739 In your documentation you explain what the plugins do, and tell the user how
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	740 to load the optional plugin: >
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	741 :packadd! fooextra
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	742
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	743 You could add this packadd command in one of your plugins, to be executed when
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	744 the optional plugin is needed.
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	745
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	746 Run the `:helptags` command to generate the doc/tags file. Including this
21825 0db0640e16e0 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 21499 diff changeset	747 generated file in the package means that the user can drop the package in the
8748 b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	748 pack directory and the help command works right away. Don't forget to re-run
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	749 the command after changing the plugin help: >
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	750 :helptags path/start/foobar/doc
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	751 :helptags path/opt/fooextra/doc
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	752
8876 47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	753
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	754 Dependencies between plugins ~
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	755 packload-two-steps
9286 64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8 Christian Brabandt <cb@256bit.org> parents: 9116 diff changeset	756 Suppose you have two plugins that depend on the same functionality. You can
8876 47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	757 put the common functionality in an autoload directory, so that it will be
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	758 found automatically. Your package would have these files:
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	759
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	760 pack/foo/start/one/plugin/one.vim >
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	761 call foolib#getit()
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	762 < pack/foo/start/two/plugin/two.vim >
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	763 call foolib#getit()
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	764 < pack/foo/start/lib/autoload/foolib.vim >
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	765 func foolib#getit()
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	766
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	767 This works, because loading packages will first add all found directories to
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	768 'runtimepath' before sourcing the plugins.
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	769
8748 b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	770 ==============================================================================
b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	771 7. Debugging scripts debug-scripts
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	772
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	773 Besides the obvious messages that you can add to your scripts to find out what
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	774 they are doing, Vim offers a debug mode. This allows you to step through a
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	775 sourced file or user function and set breakpoints.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	776
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	777 NOTE: The debugging mode is far from perfect. Debugging will have side
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	778 effects on how Vim works. You cannot use it to debug everything. For
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	779 example, the display is messed up by the debugging messages.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	780
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	781 An alternative to debug mode is setting the 'verbose' option. With a bigger
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	782 number it will give more verbose messages about what Vim is doing.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	783
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	784
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	785 STARTING DEBUG MODE debug-mode
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	786
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	787 To enter debugging mode use one of these methods:
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	788 1. Start Vim with the \|-D\| argument: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	789 vim -D file.txt
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	790 < Debugging will start as soon as the first vimrc file is sourced. This is
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	791 useful to find out what is happening when Vim is starting up. A side
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	792 effect is that Vim will switch the terminal mode before initialisations
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	793 have finished, with unpredictable results.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	794 For a GUI-only version (Windows, Macintosh) the debugging will start as
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	795 soon as the GUI window has been opened. To make this happen early, add a
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	796 ":gui" command in the vimrc file.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	797 :debug
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	798 2. Run a command with ":debug" prepended. Debugging will only be done while
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	799 this command executes. Useful for debugging a specific script or user
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	800 function. And for scripts and functions used by autocommands. Example: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	801 :debug edit test.txt.gz
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	802
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	803 3. Set a breakpoint in a sourced file or user function. You could do this in
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	804 the command line: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	805 vim -c "breakadd file */explorer.vim" .
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	806 < This will run Vim and stop in the first line of the "explorer.vim" script.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	807 Breakpoints can also be set while in debugging mode.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	808
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	809 In debugging mode every executed command is displayed before it is executed.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	810 Comment lines, empty lines and lines that are not executed are skipped. When
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	811 a line contains two commands, separated by "\|", each command will be displayed
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	812 separately.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	813
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	814
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	815 DEBUG MODE
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	816
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	817 Once in debugging mode, the usual Ex commands can be used. For example, to
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	818 inspect the value of a variable: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	819 echo idx
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	820 When inside a user function, this will print the value of the local variable
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	821 "idx". Prepend "g:" to get the value of a global variable: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	822 echo g:idx
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	823 All commands are executed in the context of the current function or script.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	824 You can also set options, for example setting or resetting 'verbose' will show
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	825 what happens, but you might want to set it just before executing the lines you
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	826 are interested in: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	827 :set verbose=20
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	828
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	829 Commands that require updating the screen should be avoided, because their
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	830 effect won't be noticed until after leaving debug mode. For example: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	831 :help
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	832 won't be very helpful.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	833
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	834 There is a separate command-line history for debug mode.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	835
26304 bb2175e5ccee Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 25773 diff changeset	836 NOTE: In Vim9 script, if a command is written at the script level and
bb2175e5ccee Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 25773 diff changeset	837 continues on the next line, not using the old way with a backslash for line
bb2175e5ccee Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 25773 diff changeset	838 continuation, only the first line is printed before the debugging prompt.
bb2175e5ccee Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 25773 diff changeset	839
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	840 The line number for a function line is relative to the start of the function.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	841 If you have trouble figuring out where you are, edit the file that defines
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	842 the function in another Vim, search for the start of the function and do
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	843 "99j". Replace "99" with the line number.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	844
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	845 Additionally, these commands can be used:
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	846 >cont
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	847 cont Continue execution until the next breakpoint is hit.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	848 >quit
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	849 quit Abort execution. This is like using CTRL-C, some
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	850 things might still be executed, doesn't abort
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	851 everything. Still stops at the next breakpoint.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	852 >next
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	853 next Execute the command and come back to debug mode when
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	854 it's finished. This steps over user function calls
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	855 and sourced files.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	856 >step
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	857 step Execute the command and come back to debug mode for
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	858 the next command. This steps into called user
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	859 functions and sourced files.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	860 >interrupt
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	861 interrupt This is like using CTRL-C, but unlike ">quit" comes
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	862 back to debug mode for the next command that is
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	863 executed. Useful for testing \|:finally\| and \|:catch\|
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	864 on interrupt exceptions.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	865 >finish
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	866 finish Finish the current script or user function and come
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	867 back to debug mode for the command after the one that
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	868 sourced or called it.
7605 8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	869 >bt
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	870 >backtrace
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	871 >where
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	872 backtrace Show the call stacktrace for current debugging session.
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	873 bt
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	874 where
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	875 >frame
8061 abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75 Christian Brabandt <cb@256bit.org> parents: 7605 diff changeset	876 frame N Goes to N backtrace level. + and - signs make movement
7605 8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	877 relative. E.g., ":frame +3" goes three frames up.
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	878 >up
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	879 up Goes one level up from call stacktrace.
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	880 >down
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	881 down Goes one level down from call stacktrace.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	882
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	883 About the additional commands in debug mode:
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	884 - There is no command-line completion for them, you get the completion for the
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	885 normal Ex commands only.
8303 88207f4b861a commit https://github.com/vim/vim/commit/dae8d21dd291df6a6679a00be64e18bca0156576 Christian Brabandt <cb@256bit.org> parents: 8246 diff changeset	886 - You can shorten them, up to a single character, unless more than one command
7605 8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	887 starts with the same letter. "f" stands for "finish", use "fr" for "frame".
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	888 - Hitting <CR> will repeat the previous one. When doing another command, this
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	889 is reset (because it's not clear what you want to repeat).
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	890 - When you want to use the Ex command with the same name, prepend a colon:
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	891 ":cont", ":next", ":finish" (or shorter).
25056 43593a5d873f Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24911 diff changeset	892 vim9-debug
43593a5d873f Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24911 diff changeset	893 When debugging a compiled :def function, "step" will stop before every
25161 84c7dc0fdcd2 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 25056 diff changeset	894 executed line, not every single instruction. Thus it works mostly like a not
25056 43593a5d873f Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24911 diff changeset	895 compiled function. Access to local variables is limited you can use: >
43593a5d873f Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24911 diff changeset	896 echo varname
43593a5d873f Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24911 diff changeset	897 But not much else.
43593a5d873f Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24911 diff changeset	898 When executing a command that is not a specific bytecode instruction but
43593a5d873f Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24911 diff changeset	899 executed like a normal Ex command, "step" will stop once in the compiled
43593a5d873f Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24911 diff changeset	900 context, where local variables can be inspected, and once just before
43593a5d873f Update runtime files Bram Moolenaar <Bram@vim.org> parents: 24911 diff changeset	901 executing the command.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	902
7605 8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	903 The backtrace shows the hierarchy of function calls, e.g.:
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	904 >bt ~
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	905 3 function One[3] ~
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	906 2 Two[3] ~
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	907 ->1 Three[3] ~
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	908 0 Four ~
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	909 line 1: let four = 4 ~
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	910
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	911 The "->" points to the current frame. Use "up", "down" and "frame N" to
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	912 select another frame.
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	913
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	914 In the current frame you can evaluate the local function variables. There is
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	915 no way to see the command at the current line yet.
8fc60af6dbf5 commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc Christian Brabandt <cb@256bit.org> parents: 7233 diff changeset	916
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	917
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	918 DEFINING BREAKPOINTS
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	919 :breaka :breakadd
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	920 :breaka[dd] func [lnum] {name}
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	921 Set a breakpoint in a function. Example: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	922 :breakadd func Explore
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	923 < Doesn't check for a valid function name, thus the breakpoint
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	924 can be set before the function is defined.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	925
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	926 :breaka[dd] file [lnum] {name}
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	927 Set a breakpoint in a sourced file. Example: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	928 :breakadd file 43 .vimrc
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	929
10 4e2284e71352 updated for version 7.0002 vimboss parents: 7 diff changeset	930 :breaka[dd] here
4e2284e71352 updated for version 7.0002 vimboss parents: 7 diff changeset	931 Set a breakpoint in the current line of the current file.
4e2284e71352 updated for version 7.0002 vimboss parents: 7 diff changeset	932 Like doing: >
4e2284e71352 updated for version 7.0002 vimboss parents: 7 diff changeset	933 :breakadd file <cursor-line> <current-file>
4e2284e71352 updated for version 7.0002 vimboss parents: 7 diff changeset	934 < Note that this only works for commands that are executed when
4e2284e71352 updated for version 7.0002 vimboss parents: 7 diff changeset	935 sourcing the file, not for a function defined in that file.
4e2284e71352 updated for version 7.0002 vimboss parents: 7 diff changeset	936
13262 69278c25429d patch 8.0.1505: debugger can't break on a condition Christian Brabandt <cb@256bit.org> parents: 13051 diff changeset	937 :breaka[dd] expr {expression}
69278c25429d patch 8.0.1505: debugger can't break on a condition Christian Brabandt <cb@256bit.org> parents: 13051 diff changeset	938 Sets a breakpoint, that will break whenever the {expression}
69278c25429d patch 8.0.1505: debugger can't break on a condition Christian Brabandt <cb@256bit.org> parents: 13051 diff changeset	939 evaluates to a different value. Example: >
69278c25429d patch 8.0.1505: debugger can't break on a condition Christian Brabandt <cb@256bit.org> parents: 13051 diff changeset	940 :breakadd expr g:lnum
25773 11b656e74444 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 25161 diff changeset	941 < Will break, whenever the global variable lnum changes.
13262 69278c25429d patch 8.0.1505: debugger can't break on a condition Christian Brabandt <cb@256bit.org> parents: 13051 diff changeset	942
25773 11b656e74444 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 25161 diff changeset	943 Errors in evaluation are suppressed, you can use the name of a
11b656e74444 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 25161 diff changeset	944 variable that does not exist yet. This also means you will
11b656e74444 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 25161 diff changeset	945 not notice anything if the expression has a mistake.
11b656e74444 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 25161 diff changeset	946
13262 69278c25429d patch 8.0.1505: debugger can't break on a condition Christian Brabandt <cb@256bit.org> parents: 13051 diff changeset	947 Note if you watch a \|script-variable\| this will break
69278c25429d patch 8.0.1505: debugger can't break on a condition Christian Brabandt <cb@256bit.org> parents: 13051 diff changeset	948 when switching scripts, since the script variable is only
69278c25429d patch 8.0.1505: debugger can't break on a condition Christian Brabandt <cb@256bit.org> parents: 13051 diff changeset	949 valid in the script where it has been defined and if that
69278c25429d patch 8.0.1505: debugger can't break on a condition Christian Brabandt <cb@256bit.org> parents: 13051 diff changeset	950 script is called from several other scripts, this will stop
69278c25429d patch 8.0.1505: debugger can't break on a condition Christian Brabandt <cb@256bit.org> parents: 13051 diff changeset	951 whenever that particular variable will become visible or
24024 ef454a7f485d Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 23938 diff changeset	952 inaccessible again.
13262 69278c25429d patch 8.0.1505: debugger can't break on a condition Christian Brabandt <cb@256bit.org> parents: 13051 diff changeset	953
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	954 The [lnum] is the line number of the breakpoint. Vim will stop at or after
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	955 this line. When omitted line 1 is used.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	956
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	957 :debug-name
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	958 {name} is a pattern that is matched with the file or function name. The
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	959 pattern is like what is used for autocommands. There must be a full match (as
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	960 if the pattern starts with "^" and ends in "$"). A "*" matches any sequence
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	961 of characters. 'ignorecase' is not used, but "\c" can be used in the pattern
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	962 to ignore case \|/\c\|. Don't include the () for the function name!
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	963
11 4424b47a0797 updated for version 7.0003 vimboss parents: 10 diff changeset	964 The match for sourced scripts is done against the full file name. If no path
4424b47a0797 updated for version 7.0003 vimboss parents: 10 diff changeset	965 is specified the current directory is used. Examples: >
4424b47a0797 updated for version 7.0003 vimboss parents: 10 diff changeset	966 breakadd file explorer.vim
4424b47a0797 updated for version 7.0003 vimboss parents: 10 diff changeset	967 matches "explorer.vim" in the current directory. >
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	968 breakadd file *explorer.vim
11 4424b47a0797 updated for version 7.0003 vimboss parents: 10 diff changeset	969 matches ".../plugin/explorer.vim", ".../plugin/iexplorer.vim", etc. >
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	970 breakadd file */explorer.vim
11 4424b47a0797 updated for version 7.0003 vimboss parents: 10 diff changeset	971 matches ".../plugin/explorer.vim" and "explorer.vim" in any other directory.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	972
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	973 The match for functions is done against the name as it's shown in the output
23717 e3720756acdc patch 8.2.2400: Vim9: compiled functions are not profiled Bram Moolenaar <Bram@vim.org> parents: 23466 diff changeset	974 of ":function". However, for local functions the script-specific prefix such
e3720756acdc patch 8.2.2400: Vim9: compiled functions are not profiled Bram Moolenaar <Bram@vim.org> parents: 23466 diff changeset	975 as "<SNR>99_" is ignored to make it easier to match script-local functions
e3720756acdc patch 8.2.2400: Vim9: compiled functions are not profiled Bram Moolenaar <Bram@vim.org> parents: 23466 diff changeset	976 without knowing the ID of the script.
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	977
148 72aefd4c1e0d updated for version 7.0046 vimboss parents: 22 diff changeset	978 Note that functions are first loaded and later executed. When they are loaded
72aefd4c1e0d updated for version 7.0046 vimboss parents: 22 diff changeset	979 the "file" breakpoints are checked, when they are executed the "func"
72aefd4c1e0d updated for version 7.0046 vimboss parents: 22 diff changeset	980 breakpoints.
72aefd4c1e0d updated for version 7.0046 vimboss parents: 22 diff changeset	981
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	982
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	983 DELETING BREAKPOINTS
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	984 :breakd :breakdel E161
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	985 :breakd[el] {nr}
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	986 Delete breakpoint {nr}. Use \|:breaklist\| to see the number of
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	987 each breakpoint.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	988
359 6c62b9b939bd updated for version 7.0093 vimboss parents: 333 diff changeset	989 :breakd[el] *
6c62b9b939bd updated for version 7.0093 vimboss parents: 333 diff changeset	990 Delete all breakpoints.
6c62b9b939bd updated for version 7.0093 vimboss parents: 333 diff changeset	991
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	992 :breakd[el] func [lnum] {name}
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	993 Delete a breakpoint in a function.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	994
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	995 :breakd[el] file [lnum] {name}
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	996 Delete a breakpoint in a sourced file.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	997
10 4e2284e71352 updated for version 7.0002 vimboss parents: 7 diff changeset	998 :breakd[el] here
4e2284e71352 updated for version 7.0002 vimboss parents: 7 diff changeset	999 Delete a breakpoint at the current line of the current file.
4e2284e71352 updated for version 7.0002 vimboss parents: 7 diff changeset	1000
7 3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1001 When [lnum] is omitted, the first breakpoint in the function or file is
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1002 deleted.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1003 The {name} must be exactly the same as what was typed for the ":breakadd"
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1004 command. "explorer", "explorer.vim" and "explorer*" are different.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1005
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1006
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1007 LISTING BREAKPOINTS
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1008 :breakl :breaklist
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1009 :breakl[ist]
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1010 List all breakpoints.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1011
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1012
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1013 OBSCURE
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1014
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1015 :debugg :debuggreedy
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1016 :debugg[reedy]
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1017 Read debug mode commands from the normal input stream, instead
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1018 of getting them directly from the user. Only useful for test
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1019 scripts. Example: >
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1020 echo 'q^Mq' \| vim -e -s -c debuggreedy -c 'breakadd file script.vim' -S script.vim
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1021
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1022 :0debugg[reedy]
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1023 Undo ":debuggreedy": get debug mode commands directly from the
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1024 user, don't use typeahead for debug commands.
3fc0f57ecb91 updated for version 7.0001 vimboss parents: diff changeset	1025
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1026 ==============================================================================
8748 b1a19a2f73f0 commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82 Christian Brabandt <cb@256bit.org> parents: 8673 diff changeset	1027 8. Profiling profile profiling
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1028
2283 7e1bd501306d Mainly documentation updates. Bram Moolenaar <bram@vim.org> parents: 2207 diff changeset	1029 Profiling means that Vim measures the time that is spent on executing
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1030 functions and/or scripts. The \|+profile\| feature is required for this.
23717 e3720756acdc patch 8.2.2400: Vim9: compiled functions are not profiled Bram Moolenaar <Bram@vim.org> parents: 23466 diff changeset	1031 It is included when Vim was compiled with "huge" features.
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1032
794 f19994020dad updated for version 7.0231 vimboss parents: 790 diff changeset	1033 You can also use the \|reltime()\| function to measure time. This only requires
23717 e3720756acdc patch 8.2.2400: Vim9: compiled functions are not profiled Bram Moolenaar <Bram@vim.org> parents: 23466 diff changeset	1034 the \|+reltime\| feature, which is present in more builds.
794 f19994020dad updated for version 7.0231 vimboss parents: 790 diff changeset	1035
5244 eb7ce2918a03 Updated runtime files. Bram Moolenaar <bram@vim.org> parents: 5239 diff changeset	1036 For profiling syntax highlighting see \|:syntime\|.
eb7ce2918a03 Updated runtime files. Bram Moolenaar <bram@vim.org> parents: 5239 diff changeset	1037
5763 c52a655d927d Update runtime files. Bram Moolenaar <bram@vim.org> parents: 5663 diff changeset	1038 For example, to profile the one_script.vim script file: >
c52a655d927d Update runtime files. Bram Moolenaar <bram@vim.org> parents: 5663 diff changeset	1039 :profile start /tmp/one_script_profile
c52a655d927d Update runtime files. Bram Moolenaar <bram@vim.org> parents: 5663 diff changeset	1040 :profile file one_script.vim
c52a655d927d Update runtime files. Bram Moolenaar <bram@vim.org> parents: 5663 diff changeset	1041 :source one_script.vim
c52a655d927d Update runtime files. Bram Moolenaar <bram@vim.org> parents: 5663 diff changeset	1042 :exit
c52a655d927d Update runtime files. Bram Moolenaar <bram@vim.org> parents: 5663 diff changeset	1043
5244 eb7ce2918a03 Updated runtime files. Bram Moolenaar <bram@vim.org> parents: 5239 diff changeset	1044
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1045 :prof[ile] start {fname} :prof :profile E750
28373 2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1046 Start profiling, write the output in {fname} upon exit or when
2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1047 a `:profile stop` or `:profile dump` command is invoked.
6757 49db2b239564 Updated runtime files. Bram Moolenaar <bram@vim.org> parents: 6476 diff changeset	1048 "~/" and environment variables in {fname} will be expanded.
790 c8680debe1cc updated for version 7.0230 vimboss parents: 716 diff changeset	1049 If {fname} already exists it will be silently overwritten.
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1050 The variable \|v:profiling\| is set to one.
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1051
28373 2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1052 :prof[ile] stop
2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1053 Write the collected profiling information to the logfile and
2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1054 stop profiling. You can use the `:profile start` command to
2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1055 clear the profiling statistics and start profiling again.
2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1056
790 c8680debe1cc updated for version 7.0230 vimboss parents: 716 diff changeset	1057 :prof[ile] pause
28373 2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1058 Don't profile until the following `:profile continue`. Can be
790 c8680debe1cc updated for version 7.0230 vimboss parents: 716 diff changeset	1059 used when doing something that should not be counted (e.g., an
c8680debe1cc updated for version 7.0230 vimboss parents: 716 diff changeset	1060 external command). Does not nest.
c8680debe1cc updated for version 7.0230 vimboss parents: 716 diff changeset	1061
c8680debe1cc updated for version 7.0230 vimboss parents: 716 diff changeset	1062 :prof[ile] continue
28373 2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1063 Continue profiling after `:profile pause`.
790 c8680debe1cc updated for version 7.0230 vimboss parents: 716 diff changeset	1064
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1065 :prof[ile] func {pattern}
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1066 Profile function that matches the pattern {pattern}.
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1067 See \|:debug-name\| for how {pattern} is used.
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1068
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1069 :prof[ile][!] file {pattern}
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1070 Profile script file that matches the pattern {pattern}.
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1071 See \|:debug-name\| for how {pattern} is used.
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1072 This only profiles the script itself, not the functions
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1073 defined in it.
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1074 When the [!] is added then all functions defined in the script
5763 c52a655d927d Update runtime files. Bram Moolenaar <bram@vim.org> parents: 5663 diff changeset	1075 will also be profiled.
c52a655d927d Update runtime files. Bram Moolenaar <bram@vim.org> parents: 5663 diff changeset	1076 Note that profiling only starts when the script is loaded
c52a655d927d Update runtime files. Bram Moolenaar <bram@vim.org> parents: 5663 diff changeset	1077 after this command. A :profile command in the script itself
c52a655d927d Update runtime files. Bram Moolenaar <bram@vim.org> parents: 5663 diff changeset	1078 won't work.
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1079
28373 2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1080 :prof[ile] dump
2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1081 Write the current state of profiling to the logfile
2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1082 immediately. After running this command, Vim continues to
2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1083 collect the profiling statistics.
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1084
364 5332dd13733c updated for version 7.0094 vimboss parents: 359 diff changeset	1085 :profd[el] ... :profd :profdel
5332dd13733c updated for version 7.0094 vimboss parents: 359 diff changeset	1086 Stop profiling for the arguments specified. See \|:breakdel\|
28373 2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1087 for the arguments. Examples: >
2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1088 profdel func MyFunc
2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1089 profdel file MyScript.vim
2ddf8aa1252c patch 8.2.4712: only get profiling information after exiting Bram Moolenaar <Bram@vim.org> parents: 28246 diff changeset	1090 profdel here
364 5332dd13733c updated for version 7.0094 vimboss parents: 359 diff changeset	1091
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1092 You must always start with a ":profile start fname" command. The resulting
23717 e3720756acdc patch 8.2.2400: Vim9: compiled functions are not profiled Bram Moolenaar <Bram@vim.org> parents: 23466 diff changeset	1093 file is written when Vim exits. For example, to profile one specific
e3720756acdc patch 8.2.2400: Vim9: compiled functions are not profiled Bram Moolenaar <Bram@vim.org> parents: 23466 diff changeset	1094 function: >
e3720756acdc patch 8.2.2400: Vim9: compiled functions are not profiled Bram Moolenaar <Bram@vim.org> parents: 23466 diff changeset	1095 profile start /tmp/vimprofile
e3720756acdc patch 8.2.2400: Vim9: compiled functions are not profiled Bram Moolenaar <Bram@vim.org> parents: 23466 diff changeset	1096 profile func MyFunc
e3720756acdc patch 8.2.2400: Vim9: compiled functions are not profiled Bram Moolenaar <Bram@vim.org> parents: 23466 diff changeset	1097
e3720756acdc patch 8.2.2400: Vim9: compiled functions are not profiled Bram Moolenaar <Bram@vim.org> parents: 23466 diff changeset	1098 Here is an example of the output, with line
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1099 numbers prepended for the explanation:
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1100
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1101 1 FUNCTION Test2() ~
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1102 2 Called 1 time ~
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1103 3 Total time: 0.155251 ~
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1104 4 Self time: 0.002006 ~
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1105 5 ~
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1106 6 count total (s) self (s) ~
856 8cd729851562 updated for version 7.0g vimboss parents: 842 diff changeset	1107 7 9 0.000096 for i in range(8) ~
8cd729851562 updated for version 7.0g vimboss parents: 842 diff changeset	1108 8 8 0.153655 0.000410 call Test3() ~
8cd729851562 updated for version 7.0g vimboss parents: 842 diff changeset	1109 9 8 0.000070 endfor ~
8cd729851562 updated for version 7.0g vimboss parents: 842 diff changeset	1110 10 " Ask a question ~
8cd729851562 updated for version 7.0g vimboss parents: 842 diff changeset	1111 11 1 0.001341 echo input("give me an answer: ") ~
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1112
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1113 The header (lines 1-4) gives the time for the whole function. The "Total"
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1114 time is the time passed while the function was executing. The "Self" time is
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1115 the "Total" time reduced by time spent in:
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1116 - other user defined functions
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1117 - sourced scripts
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1118 - executed autocommands
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1119 - external (shell) commands
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1120
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1121 Lines 7-11 show the time spent in each executed line. Lines that are not
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1122 executed do not count. Thus a comment line is never counted.
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1123
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1124 The Count column shows how many times a line was executed. Note that the
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1125 "for" command in line 7 is executed one more time as the following lines.
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1126 That is because the line is also executed to detect the end of the loop.
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1127
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1128 The time Vim spends waiting for user input isn't counted at all. Thus how
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1129 long you take to respond to the input() prompt is irrelevant.
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1130
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1131 Profiling should give a good indication of where time is spent, but keep in
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1132 mind there are various things that may clobber the results:
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1133
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1134 - The accuracy of the time measured depends on the gettimeofday() system
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1135 function. It may only be as accurate as 1/100 second, even though the times
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1136 are displayed in micro seconds.
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1137
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1138 - Real elapsed time is measured, if other processes are busy they may cause
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1139 delays at unpredictable moments. You may want to run the profiling several
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1140 times and use the lowest results.
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1141
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1142 - If you have several commands in one line you only get one time. Split the
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1143 line to see the time for the individual commands.
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1144
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1145 - The time of the lines added up is mostly less than the time of the whole
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1146 function. There is some overhead in between.
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1147
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1148 - Functions that are deleted before Vim exits will not produce profiling
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1149 information. You can check the \|v:profiling\| variable if needed: >
856 8cd729851562 updated for version 7.0g vimboss parents: 842 diff changeset	1150 :if !v:profiling
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1151 : delfunc MyFunc
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1152 :endif
8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1153 <
177 84c21eb4fc40 updated for version 7.0054 vimboss parents: 170 diff changeset	1154 - Profiling may give weird results on multi-processor systems, when sleep
84c21eb4fc40 updated for version 7.0054 vimboss parents: 170 diff changeset	1155 mode kicks in or the processor frequency is reduced to save power.
170 8c60f65311fa updated for version 7.0052 vimboss parents: 168 diff changeset	1156
1125 96cd8222a819 updated for version 7.1a vimboss parents: 874 diff changeset	1157 - The "self" time is wrong when a function is used recursively.
96cd8222a819 updated for version 7.1a vimboss parents: 874 diff changeset	1158
96cd8222a819 updated for version 7.1a vimboss parents: 874 diff changeset	1159
14421 2f7e67dd088c Update runtime files. Christian Brabandt <cb@256bit.org> parents: 14249 diff changeset	1160 vim:tw=78:ts=8:noet:ft=help:norl:

Mercurial > vim

annotate runtime/doc/repeat.txt @ 29236:0eef32b4ebbc