Mercurial > vim

annotate runtime/doc/repeat.txt @ 26812:4545b6dd8210

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