Mercurial > vim
annotate runtime/doc/repeat.txt @ 29235:fbcbc953c2ec
Added tag v8.2.5136 for changeset 96ff6c230a66c0b91cb6b1aebbb3869cb5fb0414
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Sun, 19 Jun 2022 21:15:03 +0200 |
parents | 6dd88e45d47d |
children | 0eef32b4ebbc |
rev | line source |
---|---|
28379 | 1 *repeat.txt* For Vim version 8.2. Last change: 2022 Apr 08 |
7 | 2 |
3 | |
4 VIM REFERENCE MANUAL by Bram Moolenaar | |
5 | |
6 | |
7 Repeating commands, Vim scripts and debugging *repeating* | |
8 | |
9 Chapter 26 of the user manual introduces repeating |usr_26.txt|. | |
10 | |
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 | 19 |
20 ============================================================================== | |
21 1. Single repeats *single-repeat* | |
22 | |
23 *.* | |
24 . Repeat last change, with count replaced with [count]. | |
25 Also repeat a yank command, when the 'y' flag is | |
22 | 26 included in 'cpoptions'. Does not repeat a |
27 command-line command. | |
7 | 28 |
29 Simple changes can be repeated with the "." command. Without a count, the | |
30 count of the last change is used. If you enter a count, it will replace the | |
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 | 39 |
40 *@:* | |
41 @: Repeat last command-line [count] times. | |
42 {not available when compiled without the | |
43 |+cmdline_hist| feature} | |
44 | |
45 | |
46 ============================================================================== | |
47 2. Multiple repeats *multi-repeat* | |
48 | |
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 | 50 :[range]g[lobal]/{pattern}/[cmd] |
51 Execute the Ex command [cmd] (default ":p") on the | |
52 lines within [range] where {pattern} matches. | |
53 | |
54 :[range]g[lobal]!/{pattern}/[cmd] | |
55 Execute the Ex command [cmd] (default ":p") on the | |
56 lines within [range] where {pattern} does NOT match. | |
57 | |
58 *:v* *:vglobal* | |
59 :[range]v[global]/{pattern}/[cmd] | |
60 Same as :g!. | |
61 | |
24636 | 62 Example: > |
63 :g/^Obsolete/d _ | |
64 Using the underscore after `:d` avoids clobbering registers or the clipboard. | |
65 This also makes it faster. | |
66 | |
1125 | 67 Instead of the '/' which surrounds the {pattern}, you can use any other |
5239 | 68 single byte character, but not an alphabetic character, '\', '"' or '|'. |
1125 | 69 This is useful if you want to include a '/' in the search pattern or |
70 replacement string. | |
71 | |
72 For the definition of a pattern, see |pattern|. | |
73 | |
6336 | 74 NOTE [cmd] may contain a range; see |collapse| and |edit-paragraph-join| for |
75 examples. | |
76 | |
7 | 77 The global commands work by first scanning through the [range] lines and |
78 marking each line where a match occurs (for a multi-line pattern, only the | |
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 | 82 marked line. If a line is deleted its mark disappears. |
83 The default for [range] is the whole buffer (1,$). Use "CTRL-C" to interrupt | |
84 the command. If an error message is given for a line, the command for that | |
85 line is aborted and the global command continues with the next marked or | |
86 unmarked line. | |
18831 | 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 | 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 | 96 :g/pat/normal {commands} |
97 Make sure that {commands} ends with a whole command, otherwise Vim will wait | |
98 for you to type the rest of the command for each match. The screen will not | |
99 have been updated, so you don't know what you are doing. See |:normal|. | |
100 | |
101 The undo/redo command will undo/redo the whole global command at once. | |
102 The previous context mark will only be set once (with "''" you go back to | |
103 where the cursor was before the global command). | |
104 | |
105 The global command sets both the last used search pattern and the last used | |
106 substitute pattern (this is vi compatible). This makes it easy to globally | |
107 replace a string: | |
108 :g/pat/s//PAT/g | |
109 This replaces all occurrences of "pat" with "PAT". The same can be done with: | |
110 :%s/pat/PAT/g | |
111 Which is two characters shorter! | |
112 | |
1623 | 113 When using "global" in Ex mode, a special case is using ":visual" as a |
114 command. This will move to a matching line, go to Normal mode to let you | |
115 execute commands there until you use |Q| to return to Ex mode. This will be | |
116 repeated for each matching line. While doing this you cannot use ":global". | |
117 To abort this type CTRL-C twice. | |
168 | 118 |
7 | 119 ============================================================================== |
120 3. Complex repeats *complex-repeat* | |
121 | |
122 *q* *recording* | |
123 q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"} | |
124 (uppercase to append). The 'q' command is disabled | |
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 | 132 recorded macro. |
7 | 133 |
20552 | 134 Note: The recording happens while you type, replaying |
135 the register happens as if the keys come from a | |
136 mapping. This matters, for example, for undo, which | |
137 only syncs when commands were typed. | |
138 | |
7 | 139 q Stops recording. (Implementation note: The 'q' that |
140 stops recording is not stored in the register, unless | |
16610 | 141 it was the result of a mapping) |
7 | 142 |
143 *@* | |
3445 | 144 @{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} [count] |
7 | 145 times. Note that register '%' (name of the current |
146 file) and '#' (name of the alternate file) cannot be | |
2681 | 147 used. |
148 The register is executed like a mapping, that means | |
149 that the difference between 'wildchar' and 'wildcharm' | |
20552 | 150 applies, and undo might not be synced in the same way. |
2681 | 151 For "@=" you are prompted to enter an expression. The |
152 result of the expression is then executed. | |
16610 | 153 See also |@:|. |
7 | 154 |
168 | 155 *@@* *E748* |
7 | 156 @@ Repeat the previous @{0-9a-z":*} [count] times. |
157 | |
24636 | 158 *:@* |
3445 | 159 :[addr]@{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} as an Ex |
7 | 160 command. First set cursor at line [addr] (default is |
161 current line). When the last line in the register does | |
162 not have a <CR> it will be added automatically when | |
163 the 'e' flag is present in 'cpoptions'. | |
164 For ":@=" the last used expression is used. The | |
165 result of evaluating the expression is executed as an | |
166 Ex command. | |
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 | 173 Future: Will execute the register for each line in the |
174 address range. | |
7 | 175 |
24636 | 176 :[addr]*{0-9a-z".=+} *:star-compatible* |
177 When '*' is present in 'cpoptions' |cpo-star|, use | |
178 ":*" in the same way as ":@". This is NOT the default | |
179 when 'nocompatible' is used. When the '*' flag is not | |
180 present in 'cpoptions', ":*" is an alias for ":'<,'>", | |
181 select the Visual area |:star|. | |
182 | |
7 | 183 *:@:* |
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 | 186 |
10186
a5ef9968638c
commit https://github.com/vim/vim/commit/7e1479b86c590a66b63a274c079b7f18907d45a4
Christian Brabandt <cb@256bit.org>
parents:
9644
diff
changeset
|
187 :[addr]@ *:@@* |
20241 | 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 | 190 |
191 ============================================================================== | |
192 4. Using Vim scripts *using-scripts* | |
193 | |
194 For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. | |
195 | |
196 *:so* *:source* *load-vim-script* | |
197 :so[urce] {file} Read Ex commands from {file}. These are commands that | |
198 start with a ":". | |
716 | 199 Triggers the |SourcePre| autocommand. |
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
|
200 |
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 | 213 |:vim9cmd| modifier can be used. If you use a Visual |
214 selection and type ":", the range in the form "'<,'>" | |
215 can come before it: > | |
216 :'<,'>vim9cmd source | |
217 < Otherwise the range goes after the modifier and must | |
218 have a colon prefixed, like all Vim9 ranges: > | |
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 | 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 | 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 | 235 *:source!* |
7 | 236 :so[urce]! {file} Read Vim commands from {file}. These are commands |
237 that are executed from Normal mode, like you type | |
238 them. | |
239 When used after |:global|, |:argdo|, |:windo|, | |
240 |:bufdo|, in a loop or when another command follows | |
241 the display won't be updated while executing the | |
242 commands. | |
16808 | 243 Cannot be used in the |sandbox|. |
7 | 244 |
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 | 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 | 250 |
8526
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
251 Example: > |
7 | 252 :runtime syntax/c.vim |
253 | |
254 < There can be multiple {file} arguments, separated by | |
255 spaces. Each {file} is searched for in the first | |
256 directory from 'runtimepath', then in the second | |
257 directory, etc. Use a backslash to include a space | |
258 inside {file} (although it's better not to use spaces | |
259 in file names, it causes trouble). | |
260 | |
261 When [!] is included, all found files are sourced. | |
262 When it is not included only the first found file is | |
263 sourced. | |
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 | 274 When {file} contains wildcards it is expanded to all |
275 matching files. Example: > | |
18130 | 276 :runtime! plugin/**/*.vim |
7 | 277 < This is what Vim uses to load the plugin files when |
237 | 278 starting up. This similar command: > |
18130 | 279 :runtime plugin/**/*.vim |
7 | 280 < would source the first file only. |
281 | |
282 When 'verbose' is one or higher, there is a message | |
283 when no file could be found. | |
284 When 'verbose' is two or higher, there is a message | |
285 about each searched file. | |
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 | 297 If loading packages from "pack/*/start" was skipped, |
298 then this directory is searched first: | |
299 pack/*/start/{name} ~ | |
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 | 317 loaded during initialization, see |load-plugins| (note |
318 that the loading order will be reversed, because each | |
319 directory is inserted before others). | |
22565 | 320 Note that for ftdetect scripts to be loaded |
321 you will need to write `filetype plugin indent on` | |
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 | 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 | 342 Packages will be loaded only once. Using |
343 `:packloadall` a second time will have no effect. | |
344 When the optional ! is added this command will load | |
345 packages even when done before. | |
346 | |
347 Note that when using `:packloadall` in the |vimrc| | |
348 file, the 'runtimepath' option is updated, and later | |
349 all plugins in 'runtimepath' will be loaded, which | |
350 means they are loaded again. Plugins are expected to | |
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 | 358 :scripte[ncoding] [encoding] *:scripte* *:scriptencoding* *E167* |
359 Specify the character encoding used in the script. | |
360 The following lines will be converted from [encoding] | |
361 to the value of the 'encoding' option, if they are | |
362 different. Examples: > | |
363 scriptencoding iso-8859-5 | |
364 scriptencoding cp932 | |
365 < | |
366 When [encoding] is empty, no conversion is done. This | |
367 can be used to restrict conversion to a sequence of | |
368 lines: > | |
369 scriptencoding euc-jp | |
370 ... lines to be converted ... | |
371 scriptencoding | |
372 ... not converted ... | |
373 | |
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 | 378 |
379 Don't use "ucs-2" or "ucs-4", scripts cannot be in | |
380 these encodings (they would contain NUL bytes). | |
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 | 383 to use ":scriptencoding utf-8" then. |
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 | 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 | 392 *E999* *E984* *E1040* |
16267 | 393 Specify the version of Vim for the lines that follow |
394 in the same file. Only applies at the toplevel of | |
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 | 404 Marks a script file as containing |Vim9-script| |
27321 | 405 commands. Also see |vim9-namespace|. *E1038* |
406 Must be the first command in the file. *E1039* | |
23466 | 407 For [noclear] see |vim9-reload|. |
408 Without the |+eval| feature this changes the syntax | |
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 | 412 |
6476 | 413 *:scr* *:scriptnames* |
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 | 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 | 424 Edit script {scriptId}. Although ":scriptnames name" |
425 works, using ":script name" is recommended. | |
426 When the current buffer can't be |abandon|ed and the ! | |
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 | 429 *:fini* *:finish* *E168* |
430 :fini[sh] Stop sourcing a script. Can only be used in a Vim | |
431 script file. This is a quick way to skip the rest of | |
432 the file. If it is used after a |:try| but before the | |
433 matching |:finally| (if present), the commands | |
434 following the ":finally" up to the matching |:endtry| | |
435 are executed first. This process applies to all | |
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 | 438 |
439 All commands and command sequences can be repeated by putting them in a named | |
440 register and then executing it. There are two ways to get the commands in the | |
441 register: | |
442 - Use the record command "q". You type the commands once, and while they are | |
443 being executed they are stored in a register. Easy, because you can see | |
444 what you are doing. If you make a mistake, "p"ut the register into the | |
445 file, edit the command sequence, and then delete it into the register | |
446 again. You can continue recording by appending to the register (use an | |
447 uppercase letter). | |
448 - Delete or yank the command sequence into the register. | |
449 | |
450 Often used command sequences can be put under a function key with the ':map' | |
451 command. | |
452 | |
453 An alternative is to put the commands in a file, and execute them with the | |
454 ':source!' command. Useful for long command sequences. Can be combined with | |
455 the ':map' command to put complicated commands under a function key. | |
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 | 461 |
462 Example: When you give the ":!ls" command you get the |hit-enter| prompt. If | |
463 you ':source' a file with the line "!ls" in it, you will have to type the | |
464 <Enter> yourself. But if you ':source!' a file with the line ":!ls" in it, | |
465 the next characters from that file are read until a <CR> is found. You will | |
466 not have to type <CR> yourself, unless ":!ls" was the last line in the file. | |
467 | |
468 It is possible to put ':source[!]' commands in the script file, so you can | |
469 make a top-down hierarchy of script files. The ':source' command can be | |
470 nested as deep as the number of files that can be opened at one time (about | |
471 15). The ':source!' command can be nested up to 15 levels deep. | |
472 | |
473 You can use the "<sfile>" string (literally, this is not a special key) inside | |
474 of the sourced file, in places where a file name is expected. It will be | |
475 replaced by the file name of the sourced file. For example, if you have a | |
476 "other.vimrc" file in the same directory as your ".vimrc" file, you can source | |
477 it from your ".vimrc" file with this command: > | |
478 :source <sfile>:h/other.vimrc | |
479 | |
480 In script files terminal-dependent key codes are represented by | |
481 terminal-independent two character codes. This means that they can be used | |
482 in the same way on different kinds of terminals. The first character of a | |
483 key code is 0x80 or 128, shown on the screen as "~@". The second one can be | |
484 found in the list |key-notation|. Any of these codes can also be entered | |
485 with CTRL-V followed by the three digit decimal code. This does NOT work for | |
486 the <t_xx> termcap codes, these can only be used in mappings. | |
487 | |
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 | 496 |
333 | 497 Mac Classic: Files that are read with ":source" normally have <CR> <EOL>s. |
7 | 498 These always work. If you are using a file with <NL> <EOL>s (for example, a |
499 file made on Unix), this will be recognized if 'fileformats' is not empty and | |
500 the first line does not end in a <CR>. Be careful not to use a file with <NL> | |
501 linebreaks which has a <CR> in first line. | |
502 | |
503 On other systems, Vim expects ":source"ed files to end in a <NL>. These | |
504 always work. If you are using a file with <CR><NL> <EOL>s (for example, a | |
18972 | 505 file made on MS-Windows), all lines will have a trailing <CR>. This may cause |
7 | 506 problems for some commands (e.g., mappings). There is no automatic <EOL> |
507 detection, because it's common to start with a line that defines a mapping | |
508 that ends in a <CR>, which will confuse the automaton. | |
509 | |
510 *line-continuation* | |
511 Long lines in a ":source"d Ex command script file can be split by inserting | |
512 a line continuation symbol "\" (backslash) at the start of the next line. | |
513 There can be white space before the backslash, which is ignored. | |
514 | |
515 Example: the lines > | |
516 :set comments=sr:/*,mb:*,el:*/, | |
517 \://, | |
518 \b:#, | |
519 \:%, | |
520 \n:>, | |
521 \fb:- | |
522 are interpreted as if they were given in one line: | |
523 :set comments=sr:/*,mb:*,el:*/,://,b:#,:%,n:>,fb:- | |
524 | |
525 All leading whitespace characters in the line before a backslash are ignored. | |
526 Note however that trailing whitespace in the line before it cannot be | |
527 inserted freely; it depends on the position where a command is split up | |
528 whether additional whitespace is allowed or not. | |
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 | 536 In |Vim9| script the backslash can often be omitted, but not always. |
537 See |vim9-line-continuation|. | |
538 | |
7 | 539 There is a problem with the ":append" and ":insert" commands: > |
540 :1append | |
541 \asdf | |
542 . | |
543 The backslash is seen as a line-continuation symbol, thus this results in the | |
544 command: > | |
545 :1appendasdf | |
546 . | |
547 To avoid this, add the 'C' flag to the 'cpoptions' option: > | |
548 :set cpo+=C | |
549 :1append | |
550 \asdf | |
551 . | |
552 :set cpo-=C | |
553 | |
554 Note that when the commands are inside a function, you need to add the 'C' | |
555 flag when defining the function, it is not relevant when executing it. > | |
556 :set cpo+=C | |
557 :function Foo() | |
558 :1append | |
559 \asdf | |
560 . | |
561 :endfunction | |
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 | 565 To add a comment in between the lines start with '"\ '. Notice the space |
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 | 573 |
574 Rationale: | |
575 Most programs work with a trailing backslash to indicate line | |
576 continuation. Using this in Vim would cause incompatibility with Vi. | |
577 For example for this Vi mapping: > | |
578 :map xx asdf\ | |
579 < Therefore the unusual leading backslash is used. | |
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 | 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 | 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 | 710 users can choose what they include or not. Or you can decide to use one |
21825 | 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 | 732 mkdir ~/.vim/pack |
733 cd ~/.vim/pack | |
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 | 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 | 772 |
773 Besides the obvious messages that you can add to your scripts to find out what | |
774 they are doing, Vim offers a debug mode. This allows you to step through a | |
775 sourced file or user function and set breakpoints. | |
776 | |
777 NOTE: The debugging mode is far from perfect. Debugging will have side | |
778 effects on how Vim works. You cannot use it to debug everything. For | |
779 example, the display is messed up by the debugging messages. | |
780 | |
781 An alternative to debug mode is setting the 'verbose' option. With a bigger | |
782 number it will give more verbose messages about what Vim is doing. | |
783 | |
784 | |
785 STARTING DEBUG MODE *debug-mode* | |
786 | |
787 To enter debugging mode use one of these methods: | |
788 1. Start Vim with the |-D| argument: > | |
789 vim -D file.txt | |
790 < Debugging will start as soon as the first vimrc file is sourced. This is | |
791 useful to find out what is happening when Vim is starting up. A side | |
792 effect is that Vim will switch the terminal mode before initialisations | |
793 have finished, with unpredictable results. | |
794 For a GUI-only version (Windows, Macintosh) the debugging will start as | |
795 soon as the GUI window has been opened. To make this happen early, add a | |
796 ":gui" command in the vimrc file. | |
797 *:debug* | |
798 2. Run a command with ":debug" prepended. Debugging will only be done while | |
799 this command executes. Useful for debugging a specific script or user | |
800 function. And for scripts and functions used by autocommands. Example: > | |
801 :debug edit test.txt.gz | |
802 | |
803 3. Set a breakpoint in a sourced file or user function. You could do this in | |
804 the command line: > | |
805 vim -c "breakadd file */explorer.vim" . | |
806 < This will run Vim and stop in the first line of the "explorer.vim" script. | |
807 Breakpoints can also be set while in debugging mode. | |
808 | |
809 In debugging mode every executed command is displayed before it is executed. | |
810 Comment lines, empty lines and lines that are not executed are skipped. When | |
811 a line contains two commands, separated by "|", each command will be displayed | |
812 separately. | |
813 | |
814 | |
815 DEBUG MODE | |
816 | |
817 Once in debugging mode, the usual Ex commands can be used. For example, to | |
818 inspect the value of a variable: > | |
819 echo idx | |
820 When inside a user function, this will print the value of the local variable | |
821 "idx". Prepend "g:" to get the value of a global variable: > | |
822 echo g:idx | |
823 All commands are executed in the context of the current function or script. | |
824 You can also set options, for example setting or resetting 'verbose' will show | |
825 what happens, but you might want to set it just before executing the lines you | |
826 are interested in: > | |
827 :set verbose=20 | |
828 | |
829 Commands that require updating the screen should be avoided, because their | |
830 effect won't be noticed until after leaving debug mode. For example: > | |
831 :help | |
832 won't be very helpful. | |
833 | |
834 There is a separate command-line history for debug mode. | |
835 | |
26304 | 836 NOTE: In Vim9 script, if a command is written at the script level and |
837 continues on the next line, not using the old way with a backslash for line | |
838 continuation, only the first line is printed before the debugging prompt. | |
839 | |
7 | 840 The line number for a function line is relative to the start of the function. |
841 If you have trouble figuring out where you are, edit the file that defines | |
842 the function in another Vim, search for the start of the function and do | |
843 "99j". Replace "99" with the line number. | |
844 | |
845 Additionally, these commands can be used: | |
846 *>cont* | |
847 cont Continue execution until the next breakpoint is hit. | |
848 *>quit* | |
849 quit Abort execution. This is like using CTRL-C, some | |
850 things might still be executed, doesn't abort | |
851 everything. Still stops at the next breakpoint. | |
852 *>next* | |
853 next Execute the command and come back to debug mode when | |
854 it's finished. This steps over user function calls | |
855 and sourced files. | |
856 *>step* | |
857 step Execute the command and come back to debug mode for | |
858 the next command. This steps into called user | |
859 functions and sourced files. | |
860 *>interrupt* | |
861 interrupt This is like using CTRL-C, but unlike ">quit" comes | |
862 back to debug mode for the next command that is | |
863 executed. Useful for testing |:finally| and |:catch| | |
864 on interrupt exceptions. | |
865 *>finish* | |
866 finish Finish the current script or user function and come | |
867 back to debug mode for the command after the one that | |
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 | 882 |
883 About the additional commands in debug mode: | |
884 - There is no command-line completion for them, you get the completion for the | |
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 | 888 - Hitting <CR> will repeat the previous one. When doing another command, this |
889 is reset (because it's not clear what you want to repeat). | |
890 - When you want to use the Ex command with the same name, prepend a colon: | |
891 ":cont", ":next", ":finish" (or shorter). | |
25056 | 892 *vim9-debug* |
893 When debugging a compiled :def function, "step" will stop before every | |
25161 | 894 executed line, not every single instruction. Thus it works mostly like a not |
25056 | 895 compiled function. Access to local variables is limited you can use: > |
896 echo varname | |
897 But not much else. | |
898 When executing a command that is not a specific bytecode instruction but | |
899 executed like a normal Ex command, "step" will stop once in the compiled | |
900 context, where local variables can be inspected, and once just before | |
901 executing the command. | |
7 | 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 | 917 |
918 DEFINING BREAKPOINTS | |
919 *:breaka* *:breakadd* | |
920 :breaka[dd] func [lnum] {name} | |
921 Set a breakpoint in a function. Example: > | |
922 :breakadd func Explore | |
923 < Doesn't check for a valid function name, thus the breakpoint | |
924 can be set before the function is defined. | |
925 | |
926 :breaka[dd] file [lnum] {name} | |
927 Set a breakpoint in a sourced file. Example: > | |
928 :breakadd file 43 .vimrc | |
929 | |
10 | 930 :breaka[dd] here |
931 Set a breakpoint in the current line of the current file. | |
932 Like doing: > | |
933 :breakadd file <cursor-line> <current-file> | |
934 < Note that this only works for commands that are executed when | |
935 sourcing the file, not for a function defined in that file. | |
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 | 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 | 943 Errors in evaluation are suppressed, you can use the name of a |
944 variable that does not exist yet. This also means you will | |
945 not notice anything if the expression has a mistake. | |
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 | 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 | 954 The [lnum] is the line number of the breakpoint. Vim will stop at or after |
955 this line. When omitted line 1 is used. | |
956 | |
170 | 957 *:debug-name* |
7 | 958 {name} is a pattern that is matched with the file or function name. The |
959 pattern is like what is used for autocommands. There must be a full match (as | |
960 if the pattern starts with "^" and ends in "$"). A "*" matches any sequence | |
961 of characters. 'ignorecase' is not used, but "\c" can be used in the pattern | |
962 to ignore case |/\c|. Don't include the () for the function name! | |
963 | |
11 | 964 The match for sourced scripts is done against the full file name. If no path |
965 is specified the current directory is used. Examples: > | |
966 breakadd file explorer.vim | |
967 matches "explorer.vim" in the current directory. > | |
7 | 968 breakadd file *explorer.vim |
11 | 969 matches ".../plugin/explorer.vim", ".../plugin/iexplorer.vim", etc. > |
7 | 970 breakadd file */explorer.vim |
11 | 971 matches ".../plugin/explorer.vim" and "explorer.vim" in any other directory. |
7 | 972 |
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 | 977 |
148 | 978 Note that functions are first loaded and later executed. When they are loaded |
979 the "file" breakpoints are checked, when they are executed the "func" | |
980 breakpoints. | |
981 | |
7 | 982 |
983 DELETING BREAKPOINTS | |
984 *:breakd* *:breakdel* *E161* | |
985 :breakd[el] {nr} | |
986 Delete breakpoint {nr}. Use |:breaklist| to see the number of | |
987 each breakpoint. | |
988 | |
359 | 989 :breakd[el] * |
990 Delete all breakpoints. | |
991 | |
7 | 992 :breakd[el] func [lnum] {name} |
993 Delete a breakpoint in a function. | |
994 | |
995 :breakd[el] file [lnum] {name} | |
996 Delete a breakpoint in a sourced file. | |
997 | |
10 | 998 :breakd[el] here |
999 Delete a breakpoint at the current line of the current file. | |
1000 | |
7 | 1001 When [lnum] is omitted, the first breakpoint in the function or file is |
1002 deleted. | |
1003 The {name} must be exactly the same as what was typed for the ":breakadd" | |
1004 command. "explorer", "*explorer.vim" and "*explorer*" are different. | |
1005 | |
1006 | |
1007 LISTING BREAKPOINTS | |
1008 *:breakl* *:breaklist* | |
1009 :breakl[ist] | |
1010 List all breakpoints. | |
1011 | |
1012 | |
1013 OBSCURE | |
1014 | |
1015 *:debugg* *:debuggreedy* | |
1016 :debugg[reedy] | |
1017 Read debug mode commands from the normal input stream, instead | |
1018 of getting them directly from the user. Only useful for test | |
1019 scripts. Example: > | |
1020 echo 'q^Mq' | vim -e -s -c debuggreedy -c 'breakadd file script.vim' -S script.vim | |
1021 | |
1022 :0debugg[reedy] | |
1023 Undo ":debuggreedy": get debug mode commands directly from the | |
1024 user, don't use typeahead for debug commands. | |
1025 | |
170 | 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 | 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 | 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 | 1032 |
794 | 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 | 1035 |
5244 | 1036 For profiling syntax highlighting see |:syntime|. |
1037 | |
5763 | 1038 For example, to profile the one_script.vim script file: > |
1039 :profile start /tmp/one_script_profile | |
1040 :profile file one_script.vim | |
1041 :source one_script.vim | |
1042 :exit | |
1043 | |
5244 | 1044 |
170 | 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 | 1048 "~/" and environment variables in {fname} will be expanded. |
790 | 1049 If {fname} already exists it will be silently overwritten. |
170 | 1050 The variable |v:profiling| is set to one. |
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 | 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 | 1059 used when doing something that should not be counted (e.g., an |
1060 external command). Does not nest. | |
1061 | |
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 | 1064 |
170 | 1065 :prof[ile] func {pattern} |
1066 Profile function that matches the pattern {pattern}. | |
1067 See |:debug-name| for how {pattern} is used. | |
1068 | |
1069 :prof[ile][!] file {pattern} | |
1070 Profile script file that matches the pattern {pattern}. | |
1071 See |:debug-name| for how {pattern} is used. | |
1072 This only profiles the script itself, not the functions | |
1073 defined in it. | |
1074 When the [!] is added then all functions defined in the script | |
5763 | 1075 will also be profiled. |
1076 Note that profiling only starts when the script is loaded | |
1077 after this command. A :profile command in the script itself | |
1078 won't work. | |
170 | 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 | 1084 |
364 | 1085 :profd[el] ... *:profd* *:profdel* |
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 | 1091 |
170 | 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 | 1099 numbers prepended for the explanation: |
1100 | |
1101 1 FUNCTION Test2() ~ | |
1102 2 Called 1 time ~ | |
1103 3 Total time: 0.155251 ~ | |
1104 4 Self time: 0.002006 ~ | |
1105 5 ~ | |
1106 6 count total (s) self (s) ~ | |
856 | 1107 7 9 0.000096 for i in range(8) ~ |
1108 8 8 0.153655 0.000410 call Test3() ~ | |
1109 9 8 0.000070 endfor ~ | |
1110 10 " Ask a question ~ | |
1111 11 1 0.001341 echo input("give me an answer: ") ~ | |
170 | 1112 |
1113 The header (lines 1-4) gives the time for the whole function. The "Total" | |
1114 time is the time passed while the function was executing. The "Self" time is | |
1115 the "Total" time reduced by time spent in: | |
1116 - other user defined functions | |
1117 - sourced scripts | |
1118 - executed autocommands | |
1119 - external (shell) commands | |
1120 | |
1121 Lines 7-11 show the time spent in each executed line. Lines that are not | |
1122 executed do not count. Thus a comment line is never counted. | |
1123 | |
1124 The Count column shows how many times a line was executed. Note that the | |
1125 "for" command in line 7 is executed one more time as the following lines. | |
1126 That is because the line is also executed to detect the end of the loop. | |
1127 | |
1128 The time Vim spends waiting for user input isn't counted at all. Thus how | |
1129 long you take to respond to the input() prompt is irrelevant. | |
1130 | |
1131 Profiling should give a good indication of where time is spent, but keep in | |
1132 mind there are various things that may clobber the results: | |
1133 | |
1134 - The accuracy of the time measured depends on the gettimeofday() system | |
1135 function. It may only be as accurate as 1/100 second, even though the times | |
1136 are displayed in micro seconds. | |
1137 | |
1138 - Real elapsed time is measured, if other processes are busy they may cause | |
1139 delays at unpredictable moments. You may want to run the profiling several | |
1140 times and use the lowest results. | |
1141 | |
1142 - If you have several commands in one line you only get one time. Split the | |
1143 line to see the time for the individual commands. | |
1144 | |
1145 - The time of the lines added up is mostly less than the time of the whole | |
1146 function. There is some overhead in between. | |
1147 | |
1148 - Functions that are deleted before Vim exits will not produce profiling | |
1149 information. You can check the |v:profiling| variable if needed: > | |
856 | 1150 :if !v:profiling |
170 | 1151 : delfunc MyFunc |
1152 :endif | |
1153 < | |
177 | 1154 - Profiling may give weird results on multi-processor systems, when sleep |
1155 mode kicks in or the processor frequency is reduced to save power. | |
170 | 1156 |
1125 | 1157 - The "self" time is wrong when a function is used recursively. |
1158 | |
1159 | |
14421 | 1160 vim:tw=78:ts=8:noet:ft=help:norl: |