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