Mercurial > vim
annotate runtime/doc/repeat.txt @ 8553:ed28f4f1d7cf
Added tag v7.4.1566 for changeset 96968d6bba3e17b4ccd057dcb5ac9860048fa828
author | Christian Brabandt <cb@256bit.org> |
---|---|
date | Tue, 15 Mar 2016 13:15:05 +0100 |
parents | 981cc3bef9f3 |
children | ed7251c3e2d3 |
rev | line source |
---|---|
8475
aec051e61547
commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43
Christian Brabandt <cb@256bit.org>
parents:
8440
diff
changeset
|
1 *repeat.txt* For Vim version 7.4. Last change: 2016 Mar 09 |
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 | |
11 1. Single repeats |single-repeat| | |
12 2. Multiple repeats |multi-repeat| | |
13 3. Complex repeats |complex-repeat| | |
14 4. Using Vim scripts |using-scripts| | |
8182
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
15 5. Using Vim packages |packages| |
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
16 6. Debugging scripts |debug-scripts| |
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
17 7. Profiling |profiling| |
7 | 18 |
19 ============================================================================== | |
20 1. Single repeats *single-repeat* | |
21 | |
22 *.* | |
23 . Repeat last change, with count replaced with [count]. | |
24 Also repeat a yank command, when the 'y' flag is | |
22 | 25 included in 'cpoptions'. Does not repeat a |
26 command-line command. | |
7 | 27 |
28 Simple changes can be repeated with the "." command. Without a count, the | |
29 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
|
30 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
|
31 |
1dea14d4c738
Update runtime files. Add support for systemverilog.
Bram Moolenaar <bram@vim.org>
parents:
5294
diff
changeset
|
32 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
|
33 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
|
34 to use this. |
1dea14d4c738
Update runtime files. Add support for systemverilog.
Bram Moolenaar <bram@vim.org>
parents:
5294
diff
changeset
|
35 |
1dea14d4c738
Update runtime files. Add support for systemverilog.
Bram Moolenaar <bram@vim.org>
parents:
5294
diff
changeset
|
36 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
|
37 of area is used, see |visual-repeat|. |
7 | 38 |
39 *@:* | |
40 @: Repeat last command-line [count] times. | |
41 {not available when compiled without the | |
42 |+cmdline_hist| feature} | |
43 | |
44 | |
45 ============================================================================== | |
46 2. Multiple repeats *multi-repeat* | |
47 | |
48 *:g* *:global* *E147* *E148* | |
49 :[range]g[lobal]/{pattern}/[cmd] | |
50 Execute the Ex command [cmd] (default ":p") on the | |
51 lines within [range] where {pattern} matches. | |
52 | |
53 :[range]g[lobal]!/{pattern}/[cmd] | |
54 Execute the Ex command [cmd] (default ":p") on the | |
55 lines within [range] where {pattern} does NOT match. | |
56 | |
57 *:v* *:vglobal* | |
58 :[range]v[global]/{pattern}/[cmd] | |
59 Same as :g!. | |
60 | |
1125 | 61 Instead of the '/' which surrounds the {pattern}, you can use any other |
5239 | 62 single byte character, but not an alphabetic character, '\', '"' or '|'. |
1125 | 63 This is useful if you want to include a '/' in the search pattern or |
64 replacement string. | |
65 | |
66 For the definition of a pattern, see |pattern|. | |
67 | |
6336 | 68 NOTE [cmd] may contain a range; see |collapse| and |edit-paragraph-join| for |
69 examples. | |
70 | |
7 | 71 The global commands work by first scanning through the [range] lines and |
72 marking each line where a match occurs (for a multi-line pattern, only the | |
73 start of the match matters). | |
74 In a second scan the [cmd] is executed for each marked line with its line | |
75 number prepended. For ":v" and ":g!" the command is executed for each not | |
76 marked line. If a line is deleted its mark disappears. | |
77 The default for [range] is the whole buffer (1,$). Use "CTRL-C" to interrupt | |
78 the command. If an error message is given for a line, the command for that | |
79 line is aborted and the global command continues with the next marked or | |
80 unmarked line. | |
81 | |
82 To repeat a non-Ex command, you can use the ":normal" command: > | |
83 :g/pat/normal {commands} | |
84 Make sure that {commands} ends with a whole command, otherwise Vim will wait | |
85 for you to type the rest of the command for each match. The screen will not | |
86 have been updated, so you don't know what you are doing. See |:normal|. | |
87 | |
88 The undo/redo command will undo/redo the whole global command at once. | |
89 The previous context mark will only be set once (with "''" you go back to | |
90 where the cursor was before the global command). | |
91 | |
92 The global command sets both the last used search pattern and the last used | |
93 substitute pattern (this is vi compatible). This makes it easy to globally | |
94 replace a string: | |
95 :g/pat/s//PAT/g | |
96 This replaces all occurrences of "pat" with "PAT". The same can be done with: | |
97 :%s/pat/PAT/g | |
98 Which is two characters shorter! | |
99 | |
1623 | 100 When using "global" in Ex mode, a special case is using ":visual" as a |
101 command. This will move to a matching line, go to Normal mode to let you | |
102 execute commands there until you use |Q| to return to Ex mode. This will be | |
103 repeated for each matching line. While doing this you cannot use ":global". | |
104 To abort this type CTRL-C twice. | |
168 | 105 |
7 | 106 ============================================================================== |
107 3. Complex repeats *complex-repeat* | |
108 | |
109 *q* *recording* | |
110 q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"} | |
111 (uppercase to append). The 'q' command is disabled | |
112 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
|
113 a mapping and |:normal|. |
9487ea110214
commit https://github.com/vim/vim/commit/a0ed84a26897c994512873a895b9fc54e90c6845
Christian Brabandt <cb@256bit.org>
parents:
6757
diff
changeset
|
114 |
9487ea110214
commit https://github.com/vim/vim/commit/a0ed84a26897c994512873a895b9fc54e90c6845
Christian Brabandt <cb@256bit.org>
parents:
6757
diff
changeset
|
115 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
|
116 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
|
117 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
|
118 recorded macro and the yank will overwrite the |
9487ea110214
commit https://github.com/vim/vim/commit/a0ed84a26897c994512873a895b9fc54e90c6845
Christian Brabandt <cb@256bit.org>
parents:
6757
diff
changeset
|
119 recorded macro. {Vi: no recording} |
7 | 120 |
121 q Stops recording. (Implementation note: The 'q' that | |
122 stops recording is not stored in the register, unless | |
123 it was the result of a mapping) {Vi: no recording} | |
124 | |
125 *@* | |
3445 | 126 @{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} [count] |
7 | 127 times. Note that register '%' (name of the current |
128 file) and '#' (name of the alternate file) cannot be | |
2681 | 129 used. |
130 The register is executed like a mapping, that means | |
131 that the difference between 'wildchar' and 'wildcharm' | |
132 applies. | |
133 For "@=" you are prompted to enter an expression. The | |
134 result of the expression is then executed. | |
135 See also |@:|. {Vi: only named registers} | |
7 | 136 |
168 | 137 *@@* *E748* |
7 | 138 @@ Repeat the previous @{0-9a-z":*} [count] times. |
139 | |
3445 | 140 :[addr]*{0-9a-z".=+} *:@* *:star* |
141 :[addr]@{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} as an Ex | |
7 | 142 command. First set cursor at line [addr] (default is |
143 current line). When the last line in the register does | |
144 not have a <CR> it will be added automatically when | |
145 the 'e' flag is present in 'cpoptions'. | |
146 Note that the ":*" command is only recognized when the | |
147 '*' flag is present in 'cpoptions'. This is NOT the | |
148 default when 'nocompatible' is used. | |
149 For ":@=" the last used expression is used. The | |
150 result of evaluating the expression is executed as an | |
151 Ex command. | |
152 Mappings are not recognized in these commands. | |
153 {Vi: only in some versions} Future: Will execute the | |
154 register for each line in the address range. | |
155 | |
156 *:@:* | |
157 :[addr]@: Repeat last command-line. First set cursor at line | |
158 [addr] (default is current line). {not in Vi} | |
159 | |
160 *:@@* | |
161 :[addr]@@ Repeat the previous :@{0-9a-z"}. First set cursor at | |
162 line [addr] (default is current line). {Vi: only in | |
163 some versions} | |
164 | |
165 ============================================================================== | |
166 4. Using Vim scripts *using-scripts* | |
167 | |
168 For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. | |
169 | |
170 *:so* *:source* *load-vim-script* | |
171 :so[urce] {file} Read Ex commands from {file}. These are commands that | |
172 start with a ":". | |
716 | 173 Triggers the |SourcePre| autocommand. |
7 | 174 |
175 :so[urce]! {file} Read Vim commands from {file}. These are commands | |
176 that are executed from Normal mode, like you type | |
177 them. | |
178 When used after |:global|, |:argdo|, |:windo|, | |
179 |:bufdo|, in a loop or when another command follows | |
180 the display won't be updated while executing the | |
181 commands. | |
182 {not in Vi} | |
183 | |
184 *:ru* *:runtime* | |
8526
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
185 :ru[ntime][!] [where] {file} .. |
7 | 186 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
|
187 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
|
188 for non-existing files. |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
189 |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
190 Example: > |
7 | 191 :runtime syntax/c.vim |
192 | |
193 < There can be multiple {file} arguments, separated by | |
194 spaces. Each {file} is searched for in the first | |
195 directory from 'runtimepath', then in the second | |
196 directory, etc. Use a backslash to include a space | |
197 inside {file} (although it's better not to use spaces | |
198 in file names, it causes trouble). | |
199 | |
200 When [!] is included, all found files are sourced. | |
201 When it is not included only the first found file is | |
202 sourced. | |
203 | |
8526
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
204 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
|
205 Other values: |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
206 START search under "start" in 'packpath' |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
207 OPT search under "opt" in 'packpath' |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
208 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
|
209 'packpath' |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
210 ALL first use 'runtimepath', then search |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
211 under "start" and "opt" in 'packpath' |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
212 |
7 | 213 When {file} contains wildcards it is expanded to all |
214 matching files. Example: > | |
215 :runtime! plugin/*.vim | |
216 < This is what Vim uses to load the plugin files when | |
237 | 217 starting up. This similar command: > |
7 | 218 :runtime plugin/*.vim |
219 < would source the first file only. | |
220 | |
221 When 'verbose' is one or higher, there is a message | |
222 when no file could be found. | |
223 When 'verbose' is two or higher, there is a message | |
224 about each searched file. | |
225 {not in Vi} | |
226 | |
8416
1a6527cce675
commit https://github.com/vim/vim/commit/be82c254862e475a582c0717455e1db6bf96b0d0
Christian Brabandt <cb@256bit.org>
parents:
8392
diff
changeset
|
227 *:pa* *:packadd* *E919* |
8392
1bf1b88968a2
commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents:
8388
diff
changeset
|
228 :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
|
229 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
|
230 match: |
1bf1b88968a2
commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents:
8388
diff
changeset
|
231 pack/*/opt/{name} ~ |
1bf1b88968a2
commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents:
8388
diff
changeset
|
232 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
|
233 there yet. |
8303
88207f4b861a
commit https://github.com/vim/vim/commit/dae8d21dd291df6a6679a00be64e18bca0156576
Christian Brabandt <cb@256bit.org>
parents:
8246
diff
changeset
|
234 |
8182
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
235 Note that {name} is the directory name, not the name |
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
236 of the .vim file. If the "{name}/plugin" directory |
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
237 contains more than one file they are all sourced. |
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
238 |
8392
1bf1b88968a2
commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents:
8388
diff
changeset
|
239 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
|
240 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
|
241 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
|
242 for "{name}/ftdetect/*.vim" files. |
1bf1b88968a2
commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents:
8388
diff
changeset
|
243 |
1bf1b88968a2
commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents:
8388
diff
changeset
|
244 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
|
245 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
|
246 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
|
247 useful in your .vimrc. The plugins will then be |
1bf1b88968a2
commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents:
8388
diff
changeset
|
248 loaded during initialization, see |load-plugins|. |
1bf1b88968a2
commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents:
8388
diff
changeset
|
249 |
1bf1b88968a2
commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents:
8388
diff
changeset
|
250 Also see |pack-add|. |
1bf1b88968a2
commit https://github.com/vim/vim/commit/328da0dcb7be34b594725eef6dc98d3ea6516d69
Christian Brabandt <cb@256bit.org>
parents:
8388
diff
changeset
|
251 |
8526
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
252 :packloadall[!] Load all packages in the "start" directories under |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
253 'packpath'. The directories found are added to |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
254 'runtimepath'. |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
255 This normally done during startup, after loading your |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
256 .vimrc file. With this command it can be done |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
257 earlier. |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
258 Packages will be loaded only once. After this command |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
259 it won't happen again. When the optional ! is added |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
260 this command will load packages even when done before. |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
261 See |packages|. |
8182
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
262 |
7 | 263 :scripte[ncoding] [encoding] *:scripte* *:scriptencoding* *E167* |
264 Specify the character encoding used in the script. | |
265 The following lines will be converted from [encoding] | |
266 to the value of the 'encoding' option, if they are | |
267 different. Examples: > | |
268 scriptencoding iso-8859-5 | |
269 scriptencoding cp932 | |
270 < | |
271 When [encoding] is empty, no conversion is done. This | |
272 can be used to restrict conversion to a sequence of | |
273 lines: > | |
274 scriptencoding euc-jp | |
275 ... lines to be converted ... | |
276 scriptencoding | |
277 ... not converted ... | |
278 | |
279 < When conversion isn't supported by the system, there | |
280 is no error message and no conversion is done. | |
281 | |
282 Don't use "ucs-2" or "ucs-4", scripts cannot be in | |
283 these encodings (they would contain NUL bytes). | |
284 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
|
285 Mark) in utf-8 format Vim will recognize it, no need |
7 | 286 to use ":scriptencoding utf-8" then. |
287 | |
288 When compiled without the |+multi_byte| feature this | |
289 command is ignored. | |
290 {not in Vi} | |
291 | |
6476 | 292 *:scr* *:scriptnames* |
293 :scr[iptnames] List all sourced script names, in the order they were | |
7 | 294 first sourced. The number is used for the script ID |
295 |<SID>|. | |
296 {not in Vi} {not available when compiled without the | |
297 |+eval| feature} | |
298 | |
299 *:fini* *:finish* *E168* | |
300 :fini[sh] Stop sourcing a script. Can only be used in a Vim | |
301 script file. This is a quick way to skip the rest of | |
302 the file. If it is used after a |:try| but before the | |
303 matching |:finally| (if present), the commands | |
304 following the ":finally" up to the matching |:endtry| | |
305 are executed first. This process applies to all | |
306 nested ":try"s in the script. The outermost ":endtry" | |
307 then stops sourcing the script. {not in Vi} | |
308 | |
309 All commands and command sequences can be repeated by putting them in a named | |
310 register and then executing it. There are two ways to get the commands in the | |
311 register: | |
312 - Use the record command "q". You type the commands once, and while they are | |
313 being executed they are stored in a register. Easy, because you can see | |
314 what you are doing. If you make a mistake, "p"ut the register into the | |
315 file, edit the command sequence, and then delete it into the register | |
316 again. You can continue recording by appending to the register (use an | |
317 uppercase letter). | |
318 - Delete or yank the command sequence into the register. | |
319 | |
320 Often used command sequences can be put under a function key with the ':map' | |
321 command. | |
322 | |
323 An alternative is to put the commands in a file, and execute them with the | |
324 ':source!' command. Useful for long command sequences. Can be combined with | |
325 the ':map' command to put complicated commands under a function key. | |
326 | |
327 The ':source' command reads Ex commands from a file line by line. You will | |
328 have to type any needed keyboard input. The ':source!' command reads from a | |
329 script file character by character, interpreting each character as if you | |
330 typed it. | |
331 | |
332 Example: When you give the ":!ls" command you get the |hit-enter| prompt. If | |
333 you ':source' a file with the line "!ls" in it, you will have to type the | |
334 <Enter> yourself. But if you ':source!' a file with the line ":!ls" in it, | |
335 the next characters from that file are read until a <CR> is found. You will | |
336 not have to type <CR> yourself, unless ":!ls" was the last line in the file. | |
337 | |
338 It is possible to put ':source[!]' commands in the script file, so you can | |
339 make a top-down hierarchy of script files. The ':source' command can be | |
340 nested as deep as the number of files that can be opened at one time (about | |
341 15). The ':source!' command can be nested up to 15 levels deep. | |
342 | |
343 You can use the "<sfile>" string (literally, this is not a special key) inside | |
344 of the sourced file, in places where a file name is expected. It will be | |
345 replaced by the file name of the sourced file. For example, if you have a | |
346 "other.vimrc" file in the same directory as your ".vimrc" file, you can source | |
347 it from your ".vimrc" file with this command: > | |
348 :source <sfile>:h/other.vimrc | |
349 | |
350 In script files terminal-dependent key codes are represented by | |
351 terminal-independent two character codes. This means that they can be used | |
352 in the same way on different kinds of terminals. The first character of a | |
353 key code is 0x80 or 128, shown on the screen as "~@". The second one can be | |
354 found in the list |key-notation|. Any of these codes can also be entered | |
355 with CTRL-V followed by the three digit decimal code. This does NOT work for | |
356 the <t_xx> termcap codes, these can only be used in mappings. | |
357 | |
358 *:source_crnl* *W15* | |
359 MS-DOS, Win32 and OS/2: Files that are read with ":source" normally have | |
360 <CR><NL> <EOL>s. These always work. If you are using a file with <NL> <EOL>s | |
361 (for example, a file made on Unix), this will be recognized if 'fileformats' | |
362 is not empty and the first line does not end in a <CR>. This fails if the | |
363 first line has something like ":map <F1> :help^M", where "^M" is a <CR>. If | |
364 the first line ends in a <CR>, but following ones don't, you will get an error | |
365 message, because the <CR> from the first lines will be lost. | |
366 | |
333 | 367 Mac Classic: Files that are read with ":source" normally have <CR> <EOL>s. |
7 | 368 These always work. If you are using a file with <NL> <EOL>s (for example, a |
369 file made on Unix), this will be recognized if 'fileformats' is not empty and | |
370 the first line does not end in a <CR>. Be careful not to use a file with <NL> | |
371 linebreaks which has a <CR> in first line. | |
372 | |
373 On other systems, Vim expects ":source"ed files to end in a <NL>. These | |
374 always work. If you are using a file with <CR><NL> <EOL>s (for example, a | |
375 file made on MS-DOS), all lines will have a trailing <CR>. This may cause | |
376 problems for some commands (e.g., mappings). There is no automatic <EOL> | |
377 detection, because it's common to start with a line that defines a mapping | |
378 that ends in a <CR>, which will confuse the automaton. | |
379 | |
380 *line-continuation* | |
381 Long lines in a ":source"d Ex command script file can be split by inserting | |
382 a line continuation symbol "\" (backslash) at the start of the next line. | |
383 There can be white space before the backslash, which is ignored. | |
384 | |
385 Example: the lines > | |
386 :set comments=sr:/*,mb:*,el:*/, | |
387 \://, | |
388 \b:#, | |
389 \:%, | |
390 \n:>, | |
391 \fb:- | |
392 are interpreted as if they were given in one line: | |
393 :set comments=sr:/*,mb:*,el:*/,://,b:#,:%,n:>,fb:- | |
394 | |
395 All leading whitespace characters in the line before a backslash are ignored. | |
396 Note however that trailing whitespace in the line before it cannot be | |
397 inserted freely; it depends on the position where a command is split up | |
398 whether additional whitespace is allowed or not. | |
399 | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
400 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
|
401 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
|
402 :syn match Comment |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
403 \ "very long regexp" |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
404 \ keepend |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
405 |
7 | 406 There is a problem with the ":append" and ":insert" commands: > |
407 :1append | |
408 \asdf | |
409 . | |
410 The backslash is seen as a line-continuation symbol, thus this results in the | |
411 command: > | |
412 :1appendasdf | |
413 . | |
414 To avoid this, add the 'C' flag to the 'cpoptions' option: > | |
415 :set cpo+=C | |
416 :1append | |
417 \asdf | |
418 . | |
419 :set cpo-=C | |
420 | |
421 Note that when the commands are inside a function, you need to add the 'C' | |
422 flag when defining the function, it is not relevant when executing it. > | |
423 :set cpo+=C | |
424 :function Foo() | |
425 :1append | |
426 \asdf | |
427 . | |
428 :endfunction | |
429 :set cpo-=C | |
430 | |
431 Rationale: | |
432 Most programs work with a trailing backslash to indicate line | |
433 continuation. Using this in Vim would cause incompatibility with Vi. | |
434 For example for this Vi mapping: > | |
435 :map xx asdf\ | |
436 < Therefore the unusual leading backslash is used. | |
437 | |
438 ============================================================================== | |
8182
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
439 5. Using Vim packages *packages* |
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
440 |
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
441 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
|
442 advantages over normal plugins: |
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
443 - 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
|
444 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
|
445 easy to update and remove. |
8376
e448f2a5d45b
commit https://github.com/vim/vim/commit/91715873d19a1859c08eeded7848113596e2f2bd
Christian Brabandt <cb@256bit.org>
parents:
8303
diff
changeset
|
446 - 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
|
447 easy to update. |
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
448 - 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
|
449 - 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
|
450 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
|
451 |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
452 |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
453 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
|
454 |
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
455 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
|
456 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
|
457 % mkdir -p ~/.vim/pack/foo |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
458 % cd ~/.vim/pack/foo |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
459 % unzip /tmp/foopack.zip |
8182
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
460 |
8440
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
461 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
|
462 |
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
463 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
|
464 pack/foo/README.txt |
8475
aec051e61547
commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43
Christian Brabandt <cb@256bit.org>
parents:
8440
diff
changeset
|
465 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
|
466 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
|
467 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
|
468 |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
469 When Vim starts up, after processing your .vimrc, it scans all directories in |
8475
aec051e61547
commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43
Christian Brabandt <cb@256bit.org>
parents:
8440
diff
changeset
|
470 'packpath' for plugins under the "pack/*/start" directory and loads them. The |
8440
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
471 directory is added to 'runtimepath'. |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
472 |
8475
aec051e61547
commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43
Christian Brabandt <cb@256bit.org>
parents:
8440
diff
changeset
|
473 In the example Vim will find "pack/foo/start/foobar/plugin/foo.vim" and adds |
aec051e61547
commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43
Christian Brabandt <cb@256bit.org>
parents:
8440
diff
changeset
|
474 "~/.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
|
475 |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
476 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
|
477 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
|
478 |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
479 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
|
480 |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
481 Note that the files under "pack/foo/opt" or not loaded automatically, only the |
8475
aec051e61547
commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43
Christian Brabandt <cb@256bit.org>
parents:
8440
diff
changeset
|
482 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
|
483 is used. |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
484 |
8526
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
485 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
|
486 see |load-plugins|. |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
487 |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
488 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
|
489 :packloadall |
981cc3bef9f3
commit https://github.com/vim/vim/commit/8dcf259d904cfb965d31841dc74a5cfaf5a351d9
Christian Brabandt <cb@256bit.org>
parents:
8475
diff
changeset
|
490 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
|
491 only happen once. |
8440
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
492 |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
493 |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
494 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
|
495 |
8388
f5972de59001
commit https://github.com/vim/vim/commit/f3654827368e6204608036353a0360e9e7c21e02
Christian Brabandt <cb@256bit.org>
parents:
8376
diff
changeset
|
496 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
|
497 directory level: |
8475
aec051e61547
commit https://github.com/vim/vim/commit/af1a0e371e739f8dff337fd31da0ff8ffb347b43
Christian Brabandt <cb@256bit.org>
parents:
8440
diff
changeset
|
498 % 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
|
499 % 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
|
500 % unzip /tmp/someplugin.zip |
8182
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
501 |
8440
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
502 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
|
503 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
|
504 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
|
505 |
8440
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
506 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
|
507 |
8376
e448f2a5d45b
commit https://github.com/vim/vim/commit/91715873d19a1859c08eeded7848113596e2f2bd
Christian Brabandt <cb@256bit.org>
parents:
8303
diff
changeset
|
508 |
8440
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
509 Optional plugins ~ |
8388
f5972de59001
commit https://github.com/vim/vim/commit/f3654827368e6204608036353a0360e9e7c21e02
Christian Brabandt <cb@256bit.org>
parents:
8376
diff
changeset
|
510 *pack-add* |
f5972de59001
commit https://github.com/vim/vim/commit/f3654827368e6204608036353a0360e9e7c21e02
Christian Brabandt <cb@256bit.org>
parents:
8376
diff
changeset
|
511 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
|
512 :packadd foodebug |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
513 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
|
514 ~/.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
|
515 |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
516 This could be done inside always.vim, if some conditions are met. Or you |
4c6ad81d41fe
commit https://github.com/vim/vim/commit/5f148ec0b5a6cedd9129b3abac351034b83cc4f7
Christian Brabandt <cb@256bit.org>
parents:
8416
diff
changeset
|
517 could add this command to your |.vimrc|. |
8182
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
518 |
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
519 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
|
520 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
|
521 |
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
522 ============================================================================== |
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
523 6. Debugging scripts *debug-scripts* |
7 | 524 |
525 Besides the obvious messages that you can add to your scripts to find out what | |
526 they are doing, Vim offers a debug mode. This allows you to step through a | |
527 sourced file or user function and set breakpoints. | |
528 | |
529 NOTE: The debugging mode is far from perfect. Debugging will have side | |
530 effects on how Vim works. You cannot use it to debug everything. For | |
531 example, the display is messed up by the debugging messages. | |
532 {Vi does not have a debug mode} | |
533 | |
534 An alternative to debug mode is setting the 'verbose' option. With a bigger | |
535 number it will give more verbose messages about what Vim is doing. | |
536 | |
537 | |
538 STARTING DEBUG MODE *debug-mode* | |
539 | |
540 To enter debugging mode use one of these methods: | |
541 1. Start Vim with the |-D| argument: > | |
542 vim -D file.txt | |
543 < Debugging will start as soon as the first vimrc file is sourced. This is | |
544 useful to find out what is happening when Vim is starting up. A side | |
545 effect is that Vim will switch the terminal mode before initialisations | |
546 have finished, with unpredictable results. | |
547 For a GUI-only version (Windows, Macintosh) the debugging will start as | |
548 soon as the GUI window has been opened. To make this happen early, add a | |
549 ":gui" command in the vimrc file. | |
550 *:debug* | |
551 2. Run a command with ":debug" prepended. Debugging will only be done while | |
552 this command executes. Useful for debugging a specific script or user | |
553 function. And for scripts and functions used by autocommands. Example: > | |
554 :debug edit test.txt.gz | |
555 | |
556 3. Set a breakpoint in a sourced file or user function. You could do this in | |
557 the command line: > | |
558 vim -c "breakadd file */explorer.vim" . | |
559 < This will run Vim and stop in the first line of the "explorer.vim" script. | |
560 Breakpoints can also be set while in debugging mode. | |
561 | |
562 In debugging mode every executed command is displayed before it is executed. | |
563 Comment lines, empty lines and lines that are not executed are skipped. When | |
564 a line contains two commands, separated by "|", each command will be displayed | |
565 separately. | |
566 | |
567 | |
568 DEBUG MODE | |
569 | |
570 Once in debugging mode, the usual Ex commands can be used. For example, to | |
571 inspect the value of a variable: > | |
572 echo idx | |
573 When inside a user function, this will print the value of the local variable | |
574 "idx". Prepend "g:" to get the value of a global variable: > | |
575 echo g:idx | |
576 All commands are executed in the context of the current function or script. | |
577 You can also set options, for example setting or resetting 'verbose' will show | |
578 what happens, but you might want to set it just before executing the lines you | |
579 are interested in: > | |
580 :set verbose=20 | |
581 | |
582 Commands that require updating the screen should be avoided, because their | |
583 effect won't be noticed until after leaving debug mode. For example: > | |
584 :help | |
585 won't be very helpful. | |
586 | |
587 There is a separate command-line history for debug mode. | |
588 | |
589 The line number for a function line is relative to the start of the function. | |
590 If you have trouble figuring out where you are, edit the file that defines | |
591 the function in another Vim, search for the start of the function and do | |
592 "99j". Replace "99" with the line number. | |
593 | |
594 Additionally, these commands can be used: | |
595 *>cont* | |
596 cont Continue execution until the next breakpoint is hit. | |
597 *>quit* | |
598 quit Abort execution. This is like using CTRL-C, some | |
599 things might still be executed, doesn't abort | |
600 everything. Still stops at the next breakpoint. | |
601 *>next* | |
602 next Execute the command and come back to debug mode when | |
603 it's finished. This steps over user function calls | |
604 and sourced files. | |
605 *>step* | |
606 step Execute the command and come back to debug mode for | |
607 the next command. This steps into called user | |
608 functions and sourced files. | |
609 *>interrupt* | |
610 interrupt This is like using CTRL-C, but unlike ">quit" comes | |
611 back to debug mode for the next command that is | |
612 executed. Useful for testing |:finally| and |:catch| | |
613 on interrupt exceptions. | |
614 *>finish* | |
615 finish Finish the current script or user function and come | |
616 back to debug mode for the command after the one that | |
617 sourced or called it. | |
7605
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
618 *>bt* |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
619 *>backtrace* |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
620 *>where* |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
621 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
|
622 bt |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
623 where |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
624 *>frame* |
8061
abd64cf67bcf
commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents:
7605
diff
changeset
|
625 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
|
626 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
|
627 *>up* |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
628 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
|
629 *>down* |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
630 down Goes one level down from call stacktrace. |
7 | 631 |
632 About the additional commands in debug mode: | |
633 - There is no command-line completion for them, you get the completion for the | |
634 normal Ex commands only. | |
8303
88207f4b861a
commit https://github.com/vim/vim/commit/dae8d21dd291df6a6679a00be64e18bca0156576
Christian Brabandt <cb@256bit.org>
parents:
8246
diff
changeset
|
635 - 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
|
636 starts with the same letter. "f" stands for "finish", use "fr" for "frame". |
7 | 637 - Hitting <CR> will repeat the previous one. When doing another command, this |
638 is reset (because it's not clear what you want to repeat). | |
639 - When you want to use the Ex command with the same name, prepend a colon: | |
640 ":cont", ":next", ":finish" (or shorter). | |
641 | |
7605
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
642 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
|
643 >bt ~ |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
644 3 function One[3] ~ |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
645 2 Two[3] ~ |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
646 ->1 Three[3] ~ |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
647 0 Four ~ |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
648 line 1: let four = 4 ~ |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
649 |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
650 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
|
651 select another frame. |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
652 |
8fc60af6dbf5
commit https://github.com/vim/vim/commit/f1f60f859cdbb2638b3662ccf7b1d179865fe7dc
Christian Brabandt <cb@256bit.org>
parents:
7233
diff
changeset
|
653 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
|
654 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
|
655 |
7 | 656 |
657 DEFINING BREAKPOINTS | |
658 *:breaka* *:breakadd* | |
659 :breaka[dd] func [lnum] {name} | |
660 Set a breakpoint in a function. Example: > | |
661 :breakadd func Explore | |
662 < Doesn't check for a valid function name, thus the breakpoint | |
663 can be set before the function is defined. | |
664 | |
665 :breaka[dd] file [lnum] {name} | |
666 Set a breakpoint in a sourced file. Example: > | |
667 :breakadd file 43 .vimrc | |
668 | |
10 | 669 :breaka[dd] here |
670 Set a breakpoint in the current line of the current file. | |
671 Like doing: > | |
672 :breakadd file <cursor-line> <current-file> | |
673 < Note that this only works for commands that are executed when | |
674 sourcing the file, not for a function defined in that file. | |
675 | |
7 | 676 The [lnum] is the line number of the breakpoint. Vim will stop at or after |
677 this line. When omitted line 1 is used. | |
678 | |
170 | 679 *:debug-name* |
7 | 680 {name} is a pattern that is matched with the file or function name. The |
681 pattern is like what is used for autocommands. There must be a full match (as | |
682 if the pattern starts with "^" and ends in "$"). A "*" matches any sequence | |
683 of characters. 'ignorecase' is not used, but "\c" can be used in the pattern | |
684 to ignore case |/\c|. Don't include the () for the function name! | |
685 | |
11 | 686 The match for sourced scripts is done against the full file name. If no path |
687 is specified the current directory is used. Examples: > | |
688 breakadd file explorer.vim | |
689 matches "explorer.vim" in the current directory. > | |
7 | 690 breakadd file *explorer.vim |
11 | 691 matches ".../plugin/explorer.vim", ".../plugin/iexplorer.vim", etc. > |
7 | 692 breakadd file */explorer.vim |
11 | 693 matches ".../plugin/explorer.vim" and "explorer.vim" in any other directory. |
7 | 694 |
695 The match for functions is done against the name as it's shown in the output | |
696 of ":function". For local functions this means that something like "<SNR>99_" | |
697 is prepended. | |
698 | |
148 | 699 Note that functions are first loaded and later executed. When they are loaded |
700 the "file" breakpoints are checked, when they are executed the "func" | |
701 breakpoints. | |
702 | |
7 | 703 |
704 DELETING BREAKPOINTS | |
705 *:breakd* *:breakdel* *E161* | |
706 :breakd[el] {nr} | |
707 Delete breakpoint {nr}. Use |:breaklist| to see the number of | |
708 each breakpoint. | |
709 | |
359 | 710 :breakd[el] * |
711 Delete all breakpoints. | |
712 | |
7 | 713 :breakd[el] func [lnum] {name} |
714 Delete a breakpoint in a function. | |
715 | |
716 :breakd[el] file [lnum] {name} | |
717 Delete a breakpoint in a sourced file. | |
718 | |
10 | 719 :breakd[el] here |
720 Delete a breakpoint at the current line of the current file. | |
721 | |
7 | 722 When [lnum] is omitted, the first breakpoint in the function or file is |
723 deleted. | |
724 The {name} must be exactly the same as what was typed for the ":breakadd" | |
725 command. "explorer", "*explorer.vim" and "*explorer*" are different. | |
726 | |
727 | |
728 LISTING BREAKPOINTS | |
729 *:breakl* *:breaklist* | |
730 :breakl[ist] | |
731 List all breakpoints. | |
732 | |
733 | |
734 OBSCURE | |
735 | |
736 *:debugg* *:debuggreedy* | |
737 :debugg[reedy] | |
738 Read debug mode commands from the normal input stream, instead | |
739 of getting them directly from the user. Only useful for test | |
740 scripts. Example: > | |
741 echo 'q^Mq' | vim -e -s -c debuggreedy -c 'breakadd file script.vim' -S script.vim | |
742 | |
743 :0debugg[reedy] | |
744 Undo ":debuggreedy": get debug mode commands directly from the | |
745 user, don't use typeahead for debug commands. | |
746 | |
170 | 747 ============================================================================== |
8182
95d59081580f
commit https://github.com/vim/vim/commit/f6fee0e2d4341c0c2f5339c1268e5877fafd07cf
Christian Brabandt <cb@256bit.org>
parents:
8061
diff
changeset
|
748 7. Profiling *profile* *profiling* |
170 | 749 |
2283
7e1bd501306d
Mainly documentation updates.
Bram Moolenaar <bram@vim.org>
parents:
2207
diff
changeset
|
750 Profiling means that Vim measures the time that is spent on executing |
170 | 751 functions and/or scripts. The |+profile| feature is required for this. |
752 It is only included when Vim was compiled with "huge" features. | |
753 {Vi does not have profiling} | |
754 | |
794 | 755 You can also use the |reltime()| function to measure time. This only requires |
756 the |+reltime| feature, which is present more often. | |
757 | |
5244 | 758 For profiling syntax highlighting see |:syntime|. |
759 | |
5763 | 760 For example, to profile the one_script.vim script file: > |
761 :profile start /tmp/one_script_profile | |
762 :profile file one_script.vim | |
763 :source one_script.vim | |
764 :exit | |
765 | |
5244 | 766 |
170 | 767 :prof[ile] start {fname} *:prof* *:profile* *E750* |
768 Start profiling, write the output in {fname} upon exit. | |
6757 | 769 "~/" and environment variables in {fname} will be expanded. |
790 | 770 If {fname} already exists it will be silently overwritten. |
170 | 771 The variable |v:profiling| is set to one. |
772 | |
790 | 773 :prof[ile] pause |
774 Don't profile until the following ":profile continue". Can be | |
775 used when doing something that should not be counted (e.g., an | |
776 external command). Does not nest. | |
777 | |
778 :prof[ile] continue | |
779 Continue profiling after ":profile pause". | |
780 | |
170 | 781 :prof[ile] func {pattern} |
782 Profile function that matches the pattern {pattern}. | |
783 See |:debug-name| for how {pattern} is used. | |
784 | |
785 :prof[ile][!] file {pattern} | |
786 Profile script file that matches the pattern {pattern}. | |
787 See |:debug-name| for how {pattern} is used. | |
788 This only profiles the script itself, not the functions | |
789 defined in it. | |
790 When the [!] is added then all functions defined in the script | |
5763 | 791 will also be profiled. |
792 Note that profiling only starts when the script is loaded | |
793 after this command. A :profile command in the script itself | |
794 won't work. | |
170 | 795 |
796 | |
364 | 797 :profd[el] ... *:profd* *:profdel* |
798 Stop profiling for the arguments specified. See |:breakdel| | |
799 for the arguments. | |
800 | |
801 | |
170 | 802 You must always start with a ":profile start fname" command. The resulting |
803 file is written when Vim exits. Here is an example of the output, with line | |
804 numbers prepended for the explanation: | |
805 | |
806 1 FUNCTION Test2() ~ | |
807 2 Called 1 time ~ | |
808 3 Total time: 0.155251 ~ | |
809 4 Self time: 0.002006 ~ | |
810 5 ~ | |
811 6 count total (s) self (s) ~ | |
856 | 812 7 9 0.000096 for i in range(8) ~ |
813 8 8 0.153655 0.000410 call Test3() ~ | |
814 9 8 0.000070 endfor ~ | |
815 10 " Ask a question ~ | |
816 11 1 0.001341 echo input("give me an answer: ") ~ | |
170 | 817 |
818 The header (lines 1-4) gives the time for the whole function. The "Total" | |
819 time is the time passed while the function was executing. The "Self" time is | |
820 the "Total" time reduced by time spent in: | |
821 - other user defined functions | |
822 - sourced scripts | |
823 - executed autocommands | |
824 - external (shell) commands | |
825 | |
826 Lines 7-11 show the time spent in each executed line. Lines that are not | |
827 executed do not count. Thus a comment line is never counted. | |
828 | |
829 The Count column shows how many times a line was executed. Note that the | |
830 "for" command in line 7 is executed one more time as the following lines. | |
831 That is because the line is also executed to detect the end of the loop. | |
832 | |
833 The time Vim spends waiting for user input isn't counted at all. Thus how | |
834 long you take to respond to the input() prompt is irrelevant. | |
835 | |
836 Profiling should give a good indication of where time is spent, but keep in | |
837 mind there are various things that may clobber the results: | |
838 | |
839 - The accuracy of the time measured depends on the gettimeofday() system | |
840 function. It may only be as accurate as 1/100 second, even though the times | |
841 are displayed in micro seconds. | |
842 | |
843 - Real elapsed time is measured, if other processes are busy they may cause | |
844 delays at unpredictable moments. You may want to run the profiling several | |
845 times and use the lowest results. | |
846 | |
847 - If you have several commands in one line you only get one time. Split the | |
848 line to see the time for the individual commands. | |
849 | |
850 - The time of the lines added up is mostly less than the time of the whole | |
851 function. There is some overhead in between. | |
852 | |
853 - Functions that are deleted before Vim exits will not produce profiling | |
854 information. You can check the |v:profiling| variable if needed: > | |
856 | 855 :if !v:profiling |
170 | 856 : delfunc MyFunc |
857 :endif | |
858 < | |
177 | 859 - Profiling may give weird results on multi-processor systems, when sleep |
860 mode kicks in or the processor frequency is reduced to save power. | |
170 | 861 |
1125 | 862 - The "self" time is wrong when a function is used recursively. |
863 | |
864 | |
7 | 865 vim:tw=78:ts=8:ft=help:norl: |