Christian Brabandt | 4bfb899 | 2024-10-16 21:58:17 +0200 | [diff] [blame] | 1 | *repeat.txt* For Vim version 9.1. Last change: 2024 Oct 16 |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 2 | |
| 3 | |
| 4 | VIM REFERENCE MANUAL by Bram Moolenaar |
| 5 | |
| 6 | |
| 7 | Repeating commands, Vim scripts and debugging *repeating* |
| 8 | |
| 9 | Chapter 26 of the user manual introduces repeating |usr_26.txt|. |
| 10 | |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 11 | 1. Single repeats |single-repeat| |
| 12 | 2. Multiple repeats |multi-repeat| |
| 13 | 3. Complex repeats |complex-repeat| |
| 14 | 4. Using Vim scripts |using-scripts| |
| 15 | 5. Using Vim packages |packages| |
| 16 | 6. Creating Vim packages |package-create| |
| 17 | 7. Debugging scripts |debug-scripts| |
| 18 | 8. Profiling |profiling| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 19 | |
| 20 | ============================================================================== |
| 21 | 1. Single repeats *single-repeat* |
| 22 | |
| 23 | *.* |
| 24 | . Repeat last change, with count replaced with [count]. |
| 25 | Also repeat a yank command, when the 'y' flag is |
Bram Moolenaar | d4755bb | 2004-09-02 19:12:26 +0000 | [diff] [blame] | 26 | included in 'cpoptions'. Does not repeat a |
| 27 | command-line command. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 28 | |
| 29 | Simple changes can be repeated with the "." command. Without a count, the |
| 30 | count of the last change is used. If you enter a count, it will replace the |
Bram Moolenaar | 92dff18 | 2014-02-11 19:15:50 +0100 | [diff] [blame] | 31 | last one. |v:count| and |v:count1| will be set. |
| 32 | |
| 33 | If the last change included a specification of a numbered register, the |
| 34 | register number will be incremented. See |redo-register| for an example how |
| 35 | to use this. |
| 36 | |
| 37 | Note that when repeating a command that used a Visual selection, the same SIZE |
| 38 | of area is used, see |visual-repeat|. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 39 | |
| 40 | *@:* |
| 41 | @: Repeat last command-line [count] times. |
| 42 | {not available when compiled without the |
| 43 | |+cmdline_hist| feature} |
| 44 | |
| 45 | |
| 46 | ============================================================================== |
| 47 | 2. Multiple repeats *multi-repeat* |
| 48 | |
Bram Moolenaar | f84b122 | 2017-06-10 14:29:52 +0200 | [diff] [blame] | 49 | *:g* *:global* *E148* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 50 | :[range]g[lobal]/{pattern}/[cmd] |
| 51 | Execute the Ex command [cmd] (default ":p") on the |
| 52 | lines within [range] where {pattern} matches. |
| 53 | |
| 54 | :[range]g[lobal]!/{pattern}/[cmd] |
| 55 | Execute the Ex command [cmd] (default ":p") on the |
| 56 | lines within [range] where {pattern} does NOT match. |
| 57 | |
| 58 | *:v* *:vglobal* |
| 59 | :[range]v[global]/{pattern}/[cmd] |
| 60 | Same as :g!. |
| 61 | |
Bram Moolenaar | 3ec3217 | 2021-05-16 12:39:47 +0200 | [diff] [blame] | 62 | Example: > |
| 63 | :g/^Obsolete/d _ |
| 64 | Using the underscore after `:d` avoids clobbering registers or the clipboard. |
| 65 | This also makes it faster. |
| 66 | |
Bram Moolenaar | c81e5e7 | 2007-05-05 18:24:42 +0000 | [diff] [blame] | 67 | Instead of the '/' which surrounds the {pattern}, you can use any other |
Bram Moolenaar | b7398fe | 2023-05-14 18:50:25 +0100 | [diff] [blame] | 68 | single byte character, but not an alphabetic character, '\', '"', '|' or '!'. |
Bram Moolenaar | c81e5e7 | 2007-05-05 18:24:42 +0000 | [diff] [blame] | 69 | This is useful if you want to include a '/' in the search pattern or |
| 70 | replacement string. |
| 71 | |
| 72 | For the definition of a pattern, see |pattern|. |
| 73 | |
Bram Moolenaar | 32efaf6 | 2014-11-05 17:02:17 +0100 | [diff] [blame] | 74 | NOTE [cmd] may contain a range; see |collapse| and |edit-paragraph-join| for |
| 75 | examples. |
| 76 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 77 | The global commands work by first scanning through the [range] lines and |
| 78 | marking each line where a match occurs (for a multi-line pattern, only the |
| 79 | start of the match matters). |
Bram Moolenaar | 03413f4 | 2016-04-12 21:07:15 +0200 | [diff] [blame] | 80 | In a second scan the [cmd] is executed for each marked line, as if the cursor |
| 81 | was in that line. For ":v" and ":g!" the command is executed for each not |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 82 | marked line. If a line is deleted its mark disappears. |
| 83 | The default for [range] is the whole buffer (1,$). Use "CTRL-C" to interrupt |
| 84 | the command. If an error message is given for a line, the command for that |
| 85 | line is aborted and the global command continues with the next marked or |
| 86 | unmarked line. |
Bram Moolenaar | 664f3cf | 2019-12-07 16:03:51 +0100 | [diff] [blame] | 87 | *E147* |
Bram Moolenaar | f84b122 | 2017-06-10 14:29:52 +0200 | [diff] [blame] | 88 | When the command is used recursively, it only works on one line. Giving a |
| 89 | range is then not allowed. This is useful to find all lines that match a |
| 90 | pattern and do not match another pattern: > |
| 91 | :g/found/v/notfound/{cmd} |
| 92 | This first finds all lines containing "found", but only executes {cmd} when |
| 93 | there is no match for "notfound". |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 94 | |
Bram Moolenaar | 9fbdbb8 | 2022-09-27 17:30:34 +0100 | [diff] [blame] | 95 | Any Ex command can be used, see |ex-cmd-index|. To execute a Normal mode |
| 96 | command, you can use the `:normal` command: > |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 97 | :g/pat/normal {commands} |
| 98 | Make sure that {commands} ends with a whole command, otherwise Vim will wait |
| 99 | for you to type the rest of the command for each match. The screen will not |
| 100 | have been updated, so you don't know what you are doing. See |:normal|. |
| 101 | |
| 102 | The undo/redo command will undo/redo the whole global command at once. |
| 103 | The previous context mark will only be set once (with "''" you go back to |
| 104 | where the cursor was before the global command). |
| 105 | |
| 106 | The global command sets both the last used search pattern and the last used |
| 107 | substitute pattern (this is vi compatible). This makes it easy to globally |
Milly | 89872f5 | 2024-10-05 17:16:18 +0200 | [diff] [blame] | 108 | replace a string: > |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 109 | :g/pat/s//PAT/g |
Milly | 89872f5 | 2024-10-05 17:16:18 +0200 | [diff] [blame] | 110 | This replaces all occurrences of "pat" with "PAT". The same can be done with: > |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 111 | :%s/pat/PAT/g |
| 112 | Which is two characters shorter! |
| 113 | |
Bram Moolenaar | 864207d | 2008-06-24 22:14:38 +0000 | [diff] [blame] | 114 | When using "global" in Ex mode, a special case is using ":visual" as a |
| 115 | command. This will move to a matching line, go to Normal mode to let you |
| 116 | execute commands there until you use |Q| to return to Ex mode. This will be |
| 117 | repeated for each matching line. While doing this you cannot use ":global". |
| 118 | To abort this type CTRL-C twice. |
Bram Moolenaar | 26a60b4 | 2005-02-22 08:49:11 +0000 | [diff] [blame] | 119 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 120 | ============================================================================== |
| 121 | 3. Complex repeats *complex-repeat* |
| 122 | |
| 123 | *q* *recording* |
| 124 | q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"} |
| 125 | (uppercase to append). The 'q' command is disabled |
| 126 | while executing a register, and it doesn't work inside |
Bram Moolenaar | a0ed84a | 2015-11-19 17:56:13 +0100 | [diff] [blame] | 127 | a mapping and |:normal|. |
| 128 | |
| 129 | Note: If the register being used for recording is also |
| 130 | used for |y| and |p| the result is most likely not |
| 131 | what is expected, because the put will paste the |
| 132 | recorded macro and the yank will overwrite the |
Bram Moolenaar | a6c27c4 | 2019-05-09 19:16:22 +0200 | [diff] [blame] | 133 | recorded macro. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 134 | |
Bram Moolenaar | 388a5d4 | 2020-05-26 21:20:45 +0200 | [diff] [blame] | 135 | Note: The recording happens while you type, replaying |
| 136 | the register happens as if the keys come from a |
| 137 | mapping. This matters, for example, for undo, which |
| 138 | only syncs when commands were typed. |
| 139 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 140 | q Stops recording. (Implementation note: The 'q' that |
| 141 | stops recording is not stored in the register, unless |
Bram Moolenaar | a6c27c4 | 2019-05-09 19:16:22 +0200 | [diff] [blame] | 142 | it was the result of a mapping) |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 143 | |
| 144 | *@* |
Bram Moolenaar | 61d35bd | 2012-03-28 20:51:51 +0200 | [diff] [blame] | 145 | @{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} [count] |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 146 | times. Note that register '%' (name of the current |
| 147 | file) and '#' (name of the alternate file) cannot be |
Bram Moolenaar | 2a8a3ec | 2011-01-08 16:06:37 +0100 | [diff] [blame] | 148 | used. |
| 149 | The register is executed like a mapping, that means |
| 150 | that the difference between 'wildchar' and 'wildcharm' |
Bram Moolenaar | 388a5d4 | 2020-05-26 21:20:45 +0200 | [diff] [blame] | 151 | applies, and undo might not be synced in the same way. |
Bram Moolenaar | 2a8a3ec | 2011-01-08 16:06:37 +0100 | [diff] [blame] | 152 | For "@=" you are prompted to enter an expression. The |
| 153 | result of the expression is then executed. |
Bram Moolenaar | a6c27c4 | 2019-05-09 19:16:22 +0200 | [diff] [blame] | 154 | See also |@:|. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 155 | |
Bram Moolenaar | 26a60b4 | 2005-02-22 08:49:11 +0000 | [diff] [blame] | 156 | *@@* *E748* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 157 | @@ Repeat the previous @{0-9a-z":*} [count] times. |
| 158 | |
Bram Moolenaar | 3ec3217 | 2021-05-16 12:39:47 +0200 | [diff] [blame] | 159 | *:@* |
Bram Moolenaar | 61d35bd | 2012-03-28 20:51:51 +0200 | [diff] [blame] | 160 | :[addr]@{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} as an Ex |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 161 | command. First set cursor at line [addr] (default is |
| 162 | current line). When the last line in the register does |
| 163 | not have a <CR> it will be added automatically when |
| 164 | the 'e' flag is present in 'cpoptions'. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 165 | For ":@=" the last used expression is used. The |
| 166 | result of evaluating the expression is executed as an |
| 167 | Ex command. |
| 168 | Mappings are not recognized in these commands. |
Bram Moolenaar | 856c111 | 2020-06-17 21:47:23 +0200 | [diff] [blame] | 169 | When the |line-continuation| character (\) is present |
| 170 | at the beginning of a line in a linewise register, |
| 171 | then it is combined with the previous line. This is |
| 172 | useful for yanking and executing parts of a Vim |
| 173 | script. |
Bram Moolenaar | a6c27c4 | 2019-05-09 19:16:22 +0200 | [diff] [blame] | 174 | Future: Will execute the register for each line in the |
| 175 | address range. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 176 | |
Bram Moolenaar | 3ec3217 | 2021-05-16 12:39:47 +0200 | [diff] [blame] | 177 | :[addr]*{0-9a-z".=+} *:star-compatible* |
| 178 | When '*' is present in 'cpoptions' |cpo-star|, use |
| 179 | ":*" in the same way as ":@". This is NOT the default |
| 180 | when 'nocompatible' is used. When the '*' flag is not |
| 181 | present in 'cpoptions', ":*" is an alias for ":'<,'>", |
| 182 | select the Visual area |:star|. |
| 183 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 184 | *:@:* |
| 185 | :[addr]@: Repeat last command-line. First set cursor at line |
Bram Moolenaar | 25c9c68 | 2019-05-05 18:13:34 +0200 | [diff] [blame] | 186 | [addr] (default is current line). |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 187 | |
Bram Moolenaar | 7e1479b | 2016-09-11 15:07:27 +0200 | [diff] [blame] | 188 | :[addr]@ *:@@* |
Bram Moolenaar | 7ceefb3 | 2020-05-01 16:07:38 +0200 | [diff] [blame] | 189 | :[addr]@@ Repeat the previous :@{register}. First set cursor at |
Bram Moolenaar | 25c9c68 | 2019-05-05 18:13:34 +0200 | [diff] [blame] | 190 | line [addr] (default is current line). |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 191 | |
| 192 | ============================================================================== |
| 193 | 4. Using Vim scripts *using-scripts* |
| 194 | |
| 195 | For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. |
| 196 | |
| 197 | *:so* *:source* *load-vim-script* |
| 198 | :so[urce] {file} Read Ex commands from {file}. These are commands that |
| 199 | start with a ":". |
Bram Moolenaar | 1f35bf9 | 2006-03-07 22:38:47 +0000 | [diff] [blame] | 200 | Triggers the |SourcePre| autocommand. |
Bram Moolenaar | d799daa | 2022-06-20 11:17:32 +0100 | [diff] [blame] | 201 | *:source-range* |
Yegappan Lakshmanan | 35dc176 | 2022-03-22 12:13:54 +0000 | [diff] [blame] | 202 | :[range]so[urce] [++clear] |
| 203 | Read Ex commands from the [range] of lines in the |
Bram Moolenaar | 9fbdbb8 | 2022-09-27 17:30:34 +0100 | [diff] [blame] | 204 | current buffer. When [range] is omitted read all |
| 205 | lines. |
Yegappan Lakshmanan | 35dc176 | 2022-03-22 12:13:54 +0000 | [diff] [blame] | 206 | |
| 207 | When sourcing commands from the current buffer, the |
| 208 | same script-ID |<SID>| is used even if the buffer is |
| 209 | sourced multiple times. If a buffer is sourced more |
| 210 | than once, then the functions in the buffer are |
| 211 | defined again. |
| 212 | |
| 213 | To source a range of lines that doesn't start with the |
| 214 | |:vim9script| command in Vim9 script context, the |
Bram Moolenaar | 46eea44 | 2022-03-30 10:51:39 +0100 | [diff] [blame] | 215 | |:vim9cmd| modifier can be used. If you use a Visual |
| 216 | selection and type ":", the range in the form "'<,'>" |
| 217 | can come before it: > |
| 218 | :'<,'>vim9cmd source |
| 219 | < Otherwise the range goes after the modifier and must |
| 220 | have a colon prefixed, like all Vim9 ranges: > |
| 221 | :vim9cmd :5,9source |
Yegappan Lakshmanan | 35dc176 | 2022-03-22 12:13:54 +0000 | [diff] [blame] | 222 | |
Bram Moolenaar | 46eea44 | 2022-03-30 10:51:39 +0100 | [diff] [blame] | 223 | < When a range of lines in a buffer is sourced in the |
Yegappan Lakshmanan | 35dc176 | 2022-03-22 12:13:54 +0000 | [diff] [blame] | 224 | Vim9 script context, the previously defined |
| 225 | script-local variables and functions are not cleared. |
| 226 | This works like the range started with the |
| 227 | ":vim9script noclear" command. The "++clear" argument |
| 228 | can be used to clear the script-local variables and |
| 229 | functions before sourcing the script. This works like |
Bram Moolenaar | 46eea44 | 2022-03-30 10:51:39 +0100 | [diff] [blame] | 230 | the range started with the `:vim9script` command |
Yegappan Lakshmanan | 35dc176 | 2022-03-22 12:13:54 +0000 | [diff] [blame] | 231 | without the "noclear" argument. See |vim9-reload| for |
| 232 | more information. |
| 233 | Examples: > |
Yegappan Lakshmanan | 35dc176 | 2022-03-22 12:13:54 +0000 | [diff] [blame] | 234 | :4,5source |
Yegappan Lakshmanan | 35dc176 | 2022-03-22 12:13:54 +0000 | [diff] [blame] | 235 | :10,18source ++clear |
Bram Moolenaar | b529cfb | 2022-07-25 15:42:07 +0100 | [diff] [blame] | 236 | < |
Bram Moolenaar | 68e6560 | 2019-05-26 21:33:31 +0200 | [diff] [blame] | 237 | *:source!* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 238 | :so[urce]! {file} Read Vim commands from {file}. These are commands |
| 239 | that are executed from Normal mode, like you type |
| 240 | them. |
| 241 | When used after |:global|, |:argdo|, |:windo|, |
| 242 | |:bufdo|, in a loop or when another command follows |
| 243 | the display won't be updated while executing the |
| 244 | commands. |
Bram Moolenaar | 68e6560 | 2019-05-26 21:33:31 +0200 | [diff] [blame] | 245 | Cannot be used in the |sandbox|. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 246 | |
| 247 | *:ru* *:runtime* |
Bram Moolenaar | 8dcf259 | 2016-03-12 22:47:14 +0100 | [diff] [blame] | 248 | :ru[ntime][!] [where] {file} .. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 249 | Read Ex commands from {file} in each directory given |
Bram Moolenaar | 8dcf259 | 2016-03-12 22:47:14 +0100 | [diff] [blame] | 250 | by 'runtimepath' and/or 'packpath'. There is no error |
| 251 | for non-existing files. |
Bram Moolenaar | 664f3cf | 2019-12-07 16:03:51 +0100 | [diff] [blame] | 252 | |
Bram Moolenaar | 8dcf259 | 2016-03-12 22:47:14 +0100 | [diff] [blame] | 253 | Example: > |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 254 | :runtime syntax/c.vim |
| 255 | |
| 256 | < There can be multiple {file} arguments, separated by |
| 257 | spaces. Each {file} is searched for in the first |
| 258 | directory from 'runtimepath', then in the second |
| 259 | directory, etc. Use a backslash to include a space |
| 260 | inside {file} (although it's better not to use spaces |
| 261 | in file names, it causes trouble). |
| 262 | |
| 263 | When [!] is included, all found files are sourced. |
| 264 | When it is not included only the first found file is |
| 265 | sourced. |
| 266 | |
Bram Moolenaar | 8dcf259 | 2016-03-12 22:47:14 +0100 | [diff] [blame] | 267 | When [where] is omitted only 'runtimepath' is used. |
| 268 | Other values: |
| 269 | START search under "start" in 'packpath' |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 270 | OPT search under "opt" in 'packpath' |
Bram Moolenaar | 8dcf259 | 2016-03-12 22:47:14 +0100 | [diff] [blame] | 271 | PACK search under "start" and "opt" in |
| 272 | 'packpath' |
| 273 | ALL first use 'runtimepath', then search |
| 274 | under "start" and "opt" in 'packpath' |
| 275 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 276 | When {file} contains wildcards it is expanded to all |
| 277 | matching files. Example: > |
Bram Moolenaar | 589edb3 | 2019-09-20 14:38:13 +0200 | [diff] [blame] | 278 | :runtime! plugin/**/*.vim |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 279 | < This is what Vim uses to load the plugin files when |
Bram Moolenaar | 13fcaaf | 2005-04-15 21:13:42 +0000 | [diff] [blame] | 280 | starting up. This similar command: > |
Bram Moolenaar | 589edb3 | 2019-09-20 14:38:13 +0200 | [diff] [blame] | 281 | :runtime plugin/**/*.vim |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 282 | < would source the first file only. |
| 283 | |
| 284 | When 'verbose' is one or higher, there is a message |
| 285 | when no file could be found. |
| 286 | When 'verbose' is two or higher, there is a message |
| 287 | about each searched file. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 288 | |
Bram Moolenaar | be82c25 | 2016-03-06 14:44:08 +0100 | [diff] [blame] | 289 | *:pa* *:packadd* *E919* |
Bram Moolenaar | 328da0d | 2016-03-04 22:22:32 +0100 | [diff] [blame] | 290 | :pa[ckadd][!] {name} Search for an optional plugin directory in 'packpath' |
| 291 | and source any plugin files found. The directory must |
| 292 | match: |
| 293 | pack/*/opt/{name} ~ |
| 294 | The directory is added to 'runtimepath' if it wasn't |
| 295 | there yet. |
Bram Moolenaar | 2685212 | 2016-05-24 20:02:38 +0200 | [diff] [blame] | 296 | If the directory pack/*/opt/{name}/after exists it is |
| 297 | added at the end of 'runtimepath'. |
Bram Moolenaar | dae8d21 | 2016-02-27 22:40:16 +0100 | [diff] [blame] | 298 | |
Bram Moolenaar | f0b03c4 | 2017-12-17 17:17:07 +0100 | [diff] [blame] | 299 | If loading packages from "pack/*/start" was skipped, |
| 300 | then this directory is searched first: |
| 301 | pack/*/start/{name} ~ |
| 302 | |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 303 | Note that {name} is the directory name, not the name |
Bram Moolenaar | 03413f4 | 2016-04-12 21:07:15 +0200 | [diff] [blame] | 304 | of the .vim file. All the files matching the pattern |
| 305 | pack/*/opt/{name}/plugin/**/*.vim ~ |
| 306 | will be sourced. This allows for using subdirectories |
| 307 | below "plugin", just like with plugins in |
| 308 | 'runtimepath'. |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 309 | |
Bram Moolenaar | 328da0d | 2016-03-04 22:22:32 +0100 | [diff] [blame] | 310 | If the filetype detection was not enabled yet (this |
Bram Moolenaar | 10e8ff9 | 2023-06-10 21:40:39 +0100 | [diff] [blame] | 311 | is usually done with a `syntax enable` or `filetype on` |
| 312 | command in your .vimrc file), this will also look |
Bram Moolenaar | 328da0d | 2016-03-04 22:22:32 +0100 | [diff] [blame] | 313 | for "{name}/ftdetect/*.vim" files. |
| 314 | |
| 315 | When the optional ! is added no plugin files or |
| 316 | ftdetect scripts are loaded, only the matching |
| 317 | directories are added to 'runtimepath'. This is |
| 318 | useful in your .vimrc. The plugins will then be |
Bram Moolenaar | 2346a63 | 2021-06-13 19:02:49 +0200 | [diff] [blame] | 319 | loaded during initialization, see |load-plugins| (note |
| 320 | that the loading order will be reversed, because each |
| 321 | directory is inserted before others). |
Bram Moolenaar | 4f4d51a | 2020-10-11 13:57:40 +0200 | [diff] [blame] | 322 | Note that for ftdetect scripts to be loaded |
| 323 | you will need to write `filetype plugin indent on` |
| 324 | AFTER all `packadd!` commands. |
Bram Moolenaar | 328da0d | 2016-03-04 22:22:32 +0100 | [diff] [blame] | 325 | |
| 326 | Also see |pack-add|. |
Bram Moolenaar | 6dc819b | 2018-07-03 16:42:19 +0200 | [diff] [blame] | 327 | {only available when compiled with |+eval|} |
Bram Moolenaar | 328da0d | 2016-03-04 22:22:32 +0100 | [diff] [blame] | 328 | |
Bram Moolenaar | e18c0b3 | 2016-03-20 21:08:34 +0100 | [diff] [blame] | 329 | *:packl* *:packloadall* |
Bram Moolenaar | 03413f4 | 2016-04-12 21:07:15 +0200 | [diff] [blame] | 330 | :packl[oadall][!] Load all packages in the "start" directory under each |
| 331 | entry in 'packpath'. |
Bram Moolenaar | 664f3cf | 2019-12-07 16:03:51 +0100 | [diff] [blame] | 332 | |
Bram Moolenaar | 03413f4 | 2016-04-12 21:07:15 +0200 | [diff] [blame] | 333 | First all the directories found are added to |
| 334 | 'runtimepath', then the plugins found in the |
| 335 | directories are sourced. This allows for a plugin to |
| 336 | depend on something of another plugin, e.g. an |
| 337 | "autoload" directory. See |packload-two-steps| for |
| 338 | how this can be useful. |
| 339 | |
Bram Moolenaar | e18c0b3 | 2016-03-20 21:08:34 +0100 | [diff] [blame] | 340 | This is normally done automatically during startup, |
| 341 | after loading your .vimrc file. With this command it |
| 342 | can be done earlier. |
Bram Moolenaar | 03413f4 | 2016-04-12 21:07:15 +0200 | [diff] [blame] | 343 | |
Bram Moolenaar | 6c1e157 | 2019-06-22 02:13:00 +0200 | [diff] [blame] | 344 | Packages will be loaded only once. Using |
| 345 | `:packloadall` a second time will have no effect. |
| 346 | When the optional ! is added this command will load |
| 347 | packages even when done before. |
| 348 | |
| 349 | Note that when using `:packloadall` in the |vimrc| |
| 350 | file, the 'runtimepath' option is updated, and later |
| 351 | all plugins in 'runtimepath' will be loaded, which |
| 352 | means they are loaded again. Plugins are expected to |
| 353 | handle that. |
Bram Moolenaar | 03413f4 | 2016-04-12 21:07:15 +0200 | [diff] [blame] | 354 | |
Bram Moolenaar | 7db8f6f | 2016-03-29 23:12:46 +0200 | [diff] [blame] | 355 | An error only causes sourcing the script where it |
Bram Moolenaar | e18c0b3 | 2016-03-20 21:08:34 +0100 | [diff] [blame] | 356 | happens to be aborted, further plugins will be loaded. |
Bram Moolenaar | 8dcf259 | 2016-03-12 22:47:14 +0100 | [diff] [blame] | 357 | See |packages|. |
Bram Moolenaar | 6dc819b | 2018-07-03 16:42:19 +0200 | [diff] [blame] | 358 | {only available when compiled with |+eval|} |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 359 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 360 | :scripte[ncoding] [encoding] *:scripte* *:scriptencoding* *E167* |
| 361 | Specify the character encoding used in the script. |
| 362 | The following lines will be converted from [encoding] |
| 363 | to the value of the 'encoding' option, if they are |
| 364 | different. Examples: > |
| 365 | scriptencoding iso-8859-5 |
| 366 | scriptencoding cp932 |
| 367 | < |
| 368 | When [encoding] is empty, no conversion is done. This |
| 369 | can be used to restrict conversion to a sequence of |
| 370 | lines: > |
| 371 | scriptencoding euc-jp |
| 372 | ... lines to be converted ... |
| 373 | scriptencoding |
| 374 | ... not converted ... |
| 375 | |
| 376 | < When conversion isn't supported by the system, there |
Bram Moolenaar | 6f1d9a0 | 2016-07-24 14:12:38 +0200 | [diff] [blame] | 377 | is no error message and no conversion is done. When a |
| 378 | line can't be converted there is no error and the |
| 379 | original line is kept. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 380 | |
| 381 | Don't use "ucs-2" or "ucs-4", scripts cannot be in |
| 382 | these encodings (they would contain NUL bytes). |
| 383 | When a sourced script starts with a BOM (Byte Order |
Bram Moolenaar | 06b5d51 | 2010-05-22 15:37:44 +0200 | [diff] [blame] | 384 | Mark) in utf-8 format Vim will recognize it, no need |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 385 | to use ":scriptencoding utf-8" then. |
| 386 | |
Bram Moolenaar | 3df0173 | 2017-02-17 22:47:16 +0100 | [diff] [blame] | 387 | If you set the 'encoding' option in your |.vimrc|, |
| 388 | `:scriptencoding` must be placed after that. E.g.: > |
| 389 | set encoding=utf-8 |
| 390 | scriptencoding utf-8 |
| 391 | < |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 392 | |
Bram Moolenaar | 558ca4a | 2019-04-04 18:15:38 +0200 | [diff] [blame] | 393 | :scriptv[ersion] {version} *:scriptv* *:scriptversion* |
Bram Moolenaar | 6f4754b | 2022-01-23 12:07:04 +0000 | [diff] [blame] | 394 | *E999* *E984* *E1040* |
Bram Moolenaar | 62e1bb4 | 2019-04-08 16:25:07 +0200 | [diff] [blame] | 395 | Specify the version of Vim for the lines that follow |
| 396 | in the same file. Only applies at the toplevel of |
| 397 | sourced scripts, not inside functions. |
Bram Moolenaar | 558ca4a | 2019-04-04 18:15:38 +0200 | [diff] [blame] | 398 | |
| 399 | If {version} is higher than what the current Vim |
| 400 | version supports E999 will be given. You either need |
| 401 | to rewrite the script to make it work with an older |
| 402 | Vim version, or update Vim to a newer version. See |
| 403 | |vimscript-version| for what changed between versions. |
| 404 | |
Bram Moolenaar | fd218c8 | 2022-01-18 16:26:24 +0000 | [diff] [blame] | 405 | :vim9s[cript] [noclear] *:vim9s* *:vim9script* |
Bram Moolenaar | 7e6a515 | 2021-01-02 16:39:53 +0100 | [diff] [blame] | 406 | Marks a script file as containing |Vim9-script| |
Bram Moolenaar | 6f4754b | 2022-01-23 12:07:04 +0000 | [diff] [blame] | 407 | commands. Also see |vim9-namespace|. *E1038* |
| 408 | Must be the first command in the file. *E1039* |
Bram Moolenaar | 7e6a515 | 2021-01-02 16:39:53 +0100 | [diff] [blame] | 409 | For [noclear] see |vim9-reload|. |
| 410 | Without the |+eval| feature this changes the syntax |
| 411 | for some commands. |
Bram Moolenaar | 39f3b14 | 2021-02-14 12:57:36 +0100 | [diff] [blame] | 412 | See |:vim9cmd| for executing one command with Vim9 |
| 413 | syntax and semantics. |
Bram Moolenaar | 2346a63 | 2021-06-13 19:02:49 +0200 | [diff] [blame] | 414 | |
Bram Moolenaar | 8feef4f | 2015-01-07 16:57:10 +0100 | [diff] [blame] | 415 | *:scr* *:scriptnames* |
| 416 | :scr[iptnames] List all sourced script names, in the order they were |
Bram Moolenaar | fd218c8 | 2022-01-18 16:26:24 +0000 | [diff] [blame] | 417 | first encountered. The number is used for the script |
| 418 | ID |<SID>|. |
Bram Moolenaar | 6079da7 | 2022-01-18 14:16:59 +0000 | [diff] [blame] | 419 | For a script that was used with `import autoload` but |
| 420 | was not actually sourced yet an "A" is shown after the |
| 421 | script ID. |
Bram Moolenaar | 753885b | 2022-08-24 16:30:36 +0100 | [diff] [blame] | 422 | For a script that was referred to by one name but |
| 423 | after resolving symbolic links got sourced with |
| 424 | another name the other script is after "->". E.g. |
| 425 | "20->22" means script 20 was sourced as script 22. |
Bram Moolenaar | dd60c36 | 2023-02-27 15:49:53 +0000 | [diff] [blame] | 426 | Also see `getscriptinfo()`. |
Bram Moolenaar | 25c9c68 | 2019-05-05 18:13:34 +0200 | [diff] [blame] | 427 | {not available when compiled without the |+eval| |
| 428 | feature} |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 429 | |
Bram Moolenaar | 07dc18f | 2018-11-30 22:48:32 +0100 | [diff] [blame] | 430 | :scr[iptnames][!] {scriptId} *:script* |
Bram Moolenaar | 9d87a37 | 2018-12-18 21:41:50 +0100 | [diff] [blame] | 431 | Edit script {scriptId}. Although ":scriptnames name" |
| 432 | works, using ":script name" is recommended. |
| 433 | When the current buffer can't be |abandon|ed and the ! |
| 434 | is not present, the command fails. |
Bram Moolenaar | 07dc18f | 2018-11-30 22:48:32 +0100 | [diff] [blame] | 435 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 436 | *:fini* *:finish* *E168* |
| 437 | :fini[sh] Stop sourcing a script. Can only be used in a Vim |
| 438 | script file. This is a quick way to skip the rest of |
| 439 | the file. If it is used after a |:try| but before the |
| 440 | matching |:finally| (if present), the commands |
| 441 | following the ":finally" up to the matching |:endtry| |
| 442 | are executed first. This process applies to all |
| 443 | nested ":try"s in the script. The outermost ":endtry" |
Bram Moolenaar | 25c9c68 | 2019-05-05 18:13:34 +0200 | [diff] [blame] | 444 | then stops sourcing the script. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 445 | |
| 446 | All commands and command sequences can be repeated by putting them in a named |
| 447 | register and then executing it. There are two ways to get the commands in the |
| 448 | register: |
| 449 | - Use the record command "q". You type the commands once, and while they are |
| 450 | being executed they are stored in a register. Easy, because you can see |
| 451 | what you are doing. If you make a mistake, "p"ut the register into the |
| 452 | file, edit the command sequence, and then delete it into the register |
| 453 | again. You can continue recording by appending to the register (use an |
| 454 | uppercase letter). |
| 455 | - Delete or yank the command sequence into the register. |
| 456 | |
| 457 | Often used command sequences can be put under a function key with the ':map' |
| 458 | command. |
| 459 | |
| 460 | An alternative is to put the commands in a file, and execute them with the |
| 461 | ':source!' command. Useful for long command sequences. Can be combined with |
| 462 | the ':map' command to put complicated commands under a function key. |
| 463 | |
Yegappan Lakshmanan | 85b43c6 | 2022-03-21 19:45:17 +0000 | [diff] [blame] | 464 | The ':source' command reads Ex commands from a file or a buffer line by line. |
| 465 | You will have to type any needed keyboard input. The ':source!' command reads |
| 466 | from a script file character by character, interpreting each character as if |
| 467 | you typed it. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 468 | |
| 469 | Example: When you give the ":!ls" command you get the |hit-enter| prompt. If |
| 470 | you ':source' a file with the line "!ls" in it, you will have to type the |
| 471 | <Enter> yourself. But if you ':source!' a file with the line ":!ls" in it, |
| 472 | the next characters from that file are read until a <CR> is found. You will |
| 473 | not have to type <CR> yourself, unless ":!ls" was the last line in the file. |
| 474 | |
| 475 | It is possible to put ':source[!]' commands in the script file, so you can |
| 476 | make a top-down hierarchy of script files. The ':source' command can be |
| 477 | nested as deep as the number of files that can be opened at one time (about |
| 478 | 15). The ':source!' command can be nested up to 15 levels deep. |
| 479 | |
| 480 | You can use the "<sfile>" string (literally, this is not a special key) inside |
| 481 | of the sourced file, in places where a file name is expected. It will be |
| 482 | replaced by the file name of the sourced file. For example, if you have a |
| 483 | "other.vimrc" file in the same directory as your ".vimrc" file, you can source |
| 484 | it from your ".vimrc" file with this command: > |
| 485 | :source <sfile>:h/other.vimrc |
| 486 | |
| 487 | In script files terminal-dependent key codes are represented by |
| 488 | terminal-independent two character codes. This means that they can be used |
| 489 | in the same way on different kinds of terminals. The first character of a |
| 490 | key code is 0x80 or 128, shown on the screen as "~@". The second one can be |
| 491 | found in the list |key-notation|. Any of these codes can also be entered |
| 492 | with CTRL-V followed by the three digit decimal code. This does NOT work for |
| 493 | the <t_xx> termcap codes, these can only be used in mappings. |
| 494 | |
| 495 | *:source_crnl* *W15* |
Bram Moolenaar | 6f345a1 | 2019-12-17 21:27:18 +0100 | [diff] [blame] | 496 | Win32: Files that are read with ":source" normally have <CR><NL> <EOL>s. |
| 497 | These always work. If you are using a file with <NL> <EOL>s (for example, a |
| 498 | file made on Unix), this will be recognized if 'fileformats' is not empty and |
| 499 | the first line does not end in a <CR>. This fails if the first line has |
| 500 | something like ":map <F1> :help^M", where "^M" is a <CR>. If the first line |
| 501 | ends in a <CR>, but following ones don't, you will get an error message, |
| 502 | because the <CR> from the first lines will be lost. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 503 | |
Bram Moolenaar | 520470a | 2005-06-16 21:59:56 +0000 | [diff] [blame] | 504 | Mac Classic: Files that are read with ":source" normally have <CR> <EOL>s. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 505 | These always work. If you are using a file with <NL> <EOL>s (for example, a |
| 506 | file made on Unix), this will be recognized if 'fileformats' is not empty and |
| 507 | the first line does not end in a <CR>. Be careful not to use a file with <NL> |
| 508 | linebreaks which has a <CR> in first line. |
| 509 | |
| 510 | On other systems, Vim expects ":source"ed files to end in a <NL>. These |
| 511 | always work. If you are using a file with <CR><NL> <EOL>s (for example, a |
Bram Moolenaar | 5666fcd | 2019-12-26 14:35:26 +0100 | [diff] [blame] | 512 | file made on MS-Windows), all lines will have a trailing <CR>. This may cause |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 513 | problems for some commands (e.g., mappings). There is no automatic <EOL> |
| 514 | detection, because it's common to start with a line that defines a mapping |
| 515 | that ends in a <CR>, which will confuse the automaton. |
| 516 | |
| 517 | *line-continuation* |
| 518 | Long lines in a ":source"d Ex command script file can be split by inserting |
| 519 | a line continuation symbol "\" (backslash) at the start of the next line. |
| 520 | There can be white space before the backslash, which is ignored. |
| 521 | |
| 522 | Example: the lines > |
| 523 | :set comments=sr:/*,mb:*,el:*/, |
| 524 | \://, |
| 525 | \b:#, |
| 526 | \:%, |
| 527 | \n:>, |
| 528 | \fb:- |
Milly | 89872f5 | 2024-10-05 17:16:18 +0200 | [diff] [blame] | 529 | are interpreted as if they were given in one line: > |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 530 | :set comments=sr:/*,mb:*,el:*/,://,b:#,:%,n:>,fb:- |
| 531 | |
| 532 | All leading whitespace characters in the line before a backslash are ignored. |
| 533 | Note however that trailing whitespace in the line before it cannot be |
| 534 | inserted freely; it depends on the position where a command is split up |
| 535 | whether additional whitespace is allowed or not. |
| 536 | |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 537 | When a space is required it's best to put it right after the backslash. A |
| 538 | space at the end of a line is hard to see and may be accidentally deleted. > |
| 539 | :syn match Comment |
| 540 | \ "very long regexp" |
| 541 | \ keepend |
| 542 | |
Bram Moolenaar | a4d131d | 2021-12-27 21:33:07 +0000 | [diff] [blame] | 543 | In |Vim9| script the backslash can often be omitted, but not always. |
| 544 | See |vim9-line-continuation|. |
| 545 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 546 | There is a problem with the ":append" and ":insert" commands: > |
| 547 | :1append |
| 548 | \asdf |
| 549 | . |
| 550 | The backslash is seen as a line-continuation symbol, thus this results in the |
| 551 | command: > |
| 552 | :1appendasdf |
| 553 | . |
| 554 | To avoid this, add the 'C' flag to the 'cpoptions' option: > |
| 555 | :set cpo+=C |
| 556 | :1append |
| 557 | \asdf |
| 558 | . |
| 559 | :set cpo-=C |
| 560 | |
| 561 | Note that when the commands are inside a function, you need to add the 'C' |
| 562 | flag when defining the function, it is not relevant when executing it. > |
| 563 | :set cpo+=C |
| 564 | :function Foo() |
| 565 | :1append |
| 566 | \asdf |
| 567 | . |
| 568 | :endfunction |
| 569 | :set cpo-=C |
Bram Moolenaar | 67f8ab8 | 2018-09-11 22:37:29 +0200 | [diff] [blame] | 570 | < |
| 571 | *line-continuation-comment* |
Bram Moolenaar | 95bafa2 | 2018-10-02 13:26:25 +0200 | [diff] [blame] | 572 | To add a comment in between the lines start with '"\ '. Notice the space |
| 573 | after the backslash. Example: > |
Bram Moolenaar | 67f8ab8 | 2018-09-11 22:37:29 +0200 | [diff] [blame] | 574 | let array = [ |
| 575 | "\ first entry comment |
| 576 | \ 'first', |
| 577 | "\ second entry comment |
| 578 | \ 'second', |
| 579 | \ ] |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 580 | |
| 581 | Rationale: |
| 582 | Most programs work with a trailing backslash to indicate line |
| 583 | continuation. Using this in Vim would cause incompatibility with Vi. |
| 584 | For example for this Vi mapping: > |
| 585 | :map xx asdf\ |
| 586 | < Therefore the unusual leading backslash is used. |
| 587 | |
Bram Moolenaar | 67f8ab8 | 2018-09-11 22:37:29 +0200 | [diff] [blame] | 588 | Starting a comment in a continuation line results in all following |
| 589 | continuation lines to be part of the comment. Since it was like this |
| 590 | for a long time, when making it possible to add a comment halfway a |
| 591 | sequence of continuation lines, it was not possible to use \", since |
| 592 | that was a valid continuation line. Using '"\ ' comes closest, even |
| 593 | though it may look a bit weird. Requiring the space after the |
| 594 | backslash is to make it very unlikely this is a normal comment line. |
| 595 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 596 | ============================================================================== |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 597 | 5. Using Vim packages *packages* |
| 598 | |
| 599 | A Vim package is a directory that contains one or more plugins. The |
| 600 | advantages over normal plugins: |
| 601 | - A package can be downloaded as an archive and unpacked in its own directory. |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 602 | Thus the files are not mixed with files of other plugins. That makes it |
| 603 | easy to update and remove. |
Bram Moolenaar | 9171587 | 2016-03-03 17:13:03 +0100 | [diff] [blame] | 604 | - A package can be a git, mercurial, etc. repository. That makes it really |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 605 | easy to update. |
| 606 | - A package can contain multiple plugins that depend on each other. |
| 607 | - A package can contain plugins that are automatically loaded on startup and |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 608 | ones that are only loaded when needed with `:packadd`. |
| 609 | |
| 610 | |
| 611 | Using a package and loading automatically ~ |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 612 | |
| 613 | Let's assume your Vim files are in the "~/.vim" directory and you want to add a |
Milly | 89872f5 | 2024-10-05 17:16:18 +0200 | [diff] [blame] | 614 | package from a zip archive "/tmp/foopack.zip": > |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 615 | % mkdir -p ~/.vim/pack/foo |
| 616 | % cd ~/.vim/pack/foo |
| 617 | % unzip /tmp/foopack.zip |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 618 | |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 619 | The directory name "foo" is arbitrary, you can pick anything you like. |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 620 | |
| 621 | You would now have these files under ~/.vim: |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 622 | pack/foo/README.txt |
Bram Moolenaar | af1a0e3 | 2016-03-09 22:19:26 +0100 | [diff] [blame] | 623 | pack/foo/start/foobar/plugin/foo.vim |
| 624 | pack/foo/start/foobar/syntax/some.vim |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 625 | pack/foo/opt/foodebug/plugin/debugger.vim |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 626 | |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 627 | When Vim starts up, after processing your .vimrc, it scans all directories in |
Bram Moolenaar | 03413f4 | 2016-04-12 21:07:15 +0200 | [diff] [blame] | 628 | 'packpath' for plugins under the "pack/*/start" directory. First all those |
| 629 | directories are added to 'runtimepath'. Then all the plugins are loaded. |
| 630 | See |packload-two-steps| for how these two steps can be useful. |
Bram Moolenaar | f365482 | 2016-03-04 22:12:23 +0100 | [diff] [blame] | 631 | |
Bram Moolenaar | 3c053a1 | 2022-10-16 13:11:12 +0100 | [diff] [blame] | 632 | To allow for calling into package functionality while parsing your .vimrc, |
| 633 | |:colorscheme| and |autoload| will both automatically search under 'packpath' |
| 634 | as well in addition to 'runtimepath'. See the documentation for each for |
| 635 | details. |
| 636 | |
Bram Moolenaar | 664f3cf | 2019-12-07 16:03:51 +0100 | [diff] [blame] | 637 | In the example Vim will find "pack/foo/start/foobar/plugin/foo.vim" and adds |
Bram Moolenaar | af1a0e3 | 2016-03-09 22:19:26 +0100 | [diff] [blame] | 638 | "~/.vim/pack/foo/start/foobar" to 'runtimepath'. |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 639 | |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 640 | If the "foobar" plugin kicks in and sets the 'filetype' to "some", Vim will |
| 641 | find the syntax/some.vim file, because its directory is in 'runtimepath'. |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 642 | |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 643 | Vim will also load ftdetect files, if there are any. |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 644 | |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 645 | Note that the files under "pack/foo/opt" are not loaded automatically, only the |
Bram Moolenaar | af1a0e3 | 2016-03-09 22:19:26 +0100 | [diff] [blame] | 646 | ones under "pack/foo/start". See |pack-add| below for how the "opt" directory |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 647 | is used. |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 648 | |
Bram Moolenaar | 8dcf259 | 2016-03-12 22:47:14 +0100 | [diff] [blame] | 649 | Loading packages automatically will not happen if loading plugins is disabled, |
| 650 | see |load-plugins|. |
| 651 | |
| 652 | To load packages earlier, so that 'runtimepath' gets updated: > |
| 653 | :packloadall |
| 654 | This also works when loading plugins is disabled. The automatic loading will |
| 655 | only happen once. |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 656 | |
Bram Moolenaar | 2685212 | 2016-05-24 20:02:38 +0200 | [diff] [blame] | 657 | If the package has an "after" directory, that directory is added to the end of |
| 658 | 'runtimepath', so that anything there will be loaded later. |
| 659 | |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 660 | |
| 661 | Using a single plugin and loading it automatically ~ |
| 662 | |
| 663 | If you don't have a package but a single plugin, you need to create the extra |
Milly | 89872f5 | 2024-10-05 17:16:18 +0200 | [diff] [blame] | 664 | directory level: > |
Bram Moolenaar | af1a0e3 | 2016-03-09 22:19:26 +0100 | [diff] [blame] | 665 | % mkdir -p ~/.vim/pack/foo/start/foobar |
| 666 | % cd ~/.vim/pack/foo/start/foobar |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 667 | % unzip /tmp/someplugin.zip |
| 668 | |
| 669 | You would now have these files: |
Bram Moolenaar | af1a0e3 | 2016-03-09 22:19:26 +0100 | [diff] [blame] | 670 | pack/foo/start/foobar/plugin/foo.vim |
| 671 | pack/foo/start/foobar/syntax/some.vim |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 672 | |
| 673 | From here it works like above. |
| 674 | |
| 675 | |
| 676 | Optional plugins ~ |
| 677 | *pack-add* |
| 678 | To load an optional plugin from a pack use the `:packadd` command: > |
| 679 | :packadd foodebug |
| 680 | This searches for "pack/*/opt/foodebug" in 'packpath' and will find |
| 681 | ~/.vim/pack/foo/opt/foodebug/plugin/debugger.vim and source it. |
| 682 | |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 683 | This could be done if some conditions are met. For example, depending on |
| 684 | whether Vim supports a feature or a dependency is missing. |
| 685 | |
| 686 | You can also load an optional plugin at startup, by putting this command in |
| 687 | your |.vimrc|: > |
| 688 | :packadd! foodebug |
Bram Moolenaar | c95a302 | 2016-06-12 23:01:46 +0200 | [diff] [blame] | 689 | The extra "!" is so that the plugin isn't loaded if Vim was started with |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 690 | |--noplugin|. |
Bram Moolenaar | 5f148ec | 2016-03-07 22:59:26 +0100 | [diff] [blame] | 691 | |
| 692 | It is perfectly normal for a package to only have files in the "opt" |
| 693 | directory. You then need to load each plugin when you want to use it. |
| 694 | |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 695 | |
| 696 | Where to put what ~ |
| 697 | |
| 698 | Since color schemes, loaded with `:colorscheme`, are found below |
| 699 | "pack/*/start" and "pack/*/opt", you could put them anywhere. We recommend |
| 700 | you put them below "pack/*/opt", for example |
| 701 | ".vim/pack/mycolors/opt/dark/colors/very_dark.vim". |
| 702 | |
| 703 | Filetype plugins should go under "pack/*/start", so that they are always |
| 704 | found. Unless you have more than one plugin for a file type and want to |
| 705 | select which one to load with `:packadd`. E.g. depending on the compiler |
| 706 | version: > |
| 707 | if foo_compiler_version > 34 |
| 708 | packadd foo_new |
| 709 | else |
| 710 | packadd foo_old |
| 711 | endif |
| 712 | |
| 713 | The "after" directory is most likely not useful in a package. It's not |
| 714 | disallowed though. |
| 715 | |
Bram Moolenaar | f6fee0e | 2016-02-21 23:02:49 +0100 | [diff] [blame] | 716 | ============================================================================== |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 717 | 6. Creating Vim packages *package-create* |
| 718 | |
| 719 | This assumes you write one or more plugins that you distribute as a package. |
| 720 | |
| 721 | If you have two unrelated plugins you would use two packages, so that Vim |
Bram Moolenaar | 2547aa9 | 2020-07-26 17:00:44 +0200 | [diff] [blame] | 722 | users can choose what they include or not. Or you can decide to use one |
Bram Moolenaar | 3d1cde8 | 2020-08-15 18:55:18 +0200 | [diff] [blame] | 723 | package with optional plugins, and tell the user to add the preferred ones with |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 724 | `:packadd`. |
| 725 | |
| 726 | Decide how you want to distribute the package. You can create an archive or |
| 727 | you could use a repository. An archive can be used by more users, but is a |
| 728 | bit harder to update to a new version. A repository can usually be kept |
| 729 | up-to-date easily, but it requires a program like "git" to be available. |
| 730 | You can do both, github can automatically create an archive for a release. |
| 731 | |
| 732 | Your directory layout would be like this: |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 733 | start/foobar/plugin/foo.vim " always loaded, defines commands |
| 734 | start/foobar/plugin/bar.vim " always loaded, defines commands |
| 735 | start/foobar/autoload/foo.vim " loaded when foo command used |
| 736 | start/foobar/doc/foo.txt " help for foo.vim |
| 737 | start/foobar/doc/tags " help tags |
RestorerZ | 9650910 | 2024-07-11 21:14:15 +0200 | [diff] [blame] | 738 | start/foobar/lang/<lang_id>/LC_MESSAGES/foobar.mo |
Christ van Willegen | ce0ef91 | 2024-06-20 23:41:59 +0200 | [diff] [blame] | 739 | " messages for the plugin in the |
| 740 | " <lang_id> language. These files are |
| 741 | " optional. |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 742 | opt/fooextra/plugin/extra.vim " optional plugin, defines commands |
| 743 | opt/fooextra/autoload/extra.vim " loaded when extra command used |
| 744 | opt/fooextra/doc/extra.txt " help for extra.vim |
| 745 | opt/fooextra/doc/tags " help tags |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 746 | |
| 747 | This allows for the user to do: > |
Bram Moolenaar | c8cdf0f | 2021-03-13 13:28:13 +0100 | [diff] [blame] | 748 | mkdir ~/.vim/pack |
| 749 | cd ~/.vim/pack |
| 750 | git clone https://github.com/you/foobar.git myfoobar |
RestorerZ | 9650910 | 2024-07-11 21:14:15 +0200 | [diff] [blame] | 751 | < |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 752 | Here "myfoobar" is a name that the user can choose, the only condition is that |
| 753 | it differs from other packages. |
| 754 | |
| 755 | In your documentation you explain what the plugins do, and tell the user how |
| 756 | to load the optional plugin: > |
| 757 | :packadd! fooextra |
RestorerZ | 9650910 | 2024-07-11 21:14:15 +0200 | [diff] [blame] | 758 | < |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 759 | You could add this packadd command in one of your plugins, to be executed when |
| 760 | the optional plugin is needed. |
| 761 | |
RestorerZ | 9650910 | 2024-07-11 21:14:15 +0200 | [diff] [blame] | 762 | *package-doc* *package-documentation* |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 763 | Run the `:helptags` command to generate the doc/tags file. Including this |
Bram Moolenaar | 3d1cde8 | 2020-08-15 18:55:18 +0200 | [diff] [blame] | 764 | generated file in the package means that the user can drop the package in the |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 765 | pack directory and the help command works right away. Don't forget to re-run |
| 766 | the command after changing the plugin help: > |
| 767 | :helptags path/start/foobar/doc |
| 768 | :helptags path/opt/fooextra/doc |
Christ van Willegen | ce0ef91 | 2024-06-20 23:41:59 +0200 | [diff] [blame] | 769 | < |
RestorerZ | 9650910 | 2024-07-11 21:14:15 +0200 | [diff] [blame] | 770 | *package-translation* |
| 771 | In order for a plugin to display translated messages, a few steps are |
| 772 | required. |
| 773 | The author of the plugin who likes to translate messages must define the name |
| 774 | of the package and the location of the directory where the translations can be |
| 775 | found using the |bindtextdomain()| function: > |
| 776 | :call bindtextdomain("foobar", |
| 777 | \ fnamemodify(expand("<script>"), ':p:h') .. '/../lang/') |
Christ van Willegen | ce0ef91 | 2024-06-20 23:41:59 +0200 | [diff] [blame] | 778 | < |
RestorerZ | 9650910 | 2024-07-11 21:14:15 +0200 | [diff] [blame] | 779 | Where: |
| 780 | "foobar" is the unique package identifier by which the |gettext()| |
| 781 | function will later search for translation strings for this |
| 782 | plugin. |
| 783 | "lang/" is the relative or absolute path to the directory structure |
| 784 | where the translation file is located. |
Christ van Willegen | ce0ef91 | 2024-06-20 23:41:59 +0200 | [diff] [blame] | 785 | |
RestorerZ | 9650910 | 2024-07-11 21:14:15 +0200 | [diff] [blame] | 786 | The directory structure where the message translation files should be placed |
| 787 | is (from the top-level directory of the package): |
| 788 | "lang/<lang_id>/LC_MESSAGES". For the format of <lang_id> see |multi-lang|. |
| 789 | This function needs to be called only once during the initialization of the |
| 790 | plugin. |
| 791 | Once this is done, the |gettext()| function can be used to retrieve translated |
| 792 | messages: > |
| 793 | :echo gettext("Hello", "foobar") |
Christ van Willegen | ce0ef91 | 2024-06-20 23:41:59 +0200 | [diff] [blame] | 794 | < |
RestorerZ | 9650910 | 2024-07-11 21:14:15 +0200 | [diff] [blame] | 795 | Where: |
h-east | 90e1fe4 | 2024-08-12 18:26:08 +0200 | [diff] [blame] | 796 | "Hello" the message "Hello" to be translated into the user's language |
| 797 | |:lang| |
RestorerZ | 9650910 | 2024-07-11 21:14:15 +0200 | [diff] [blame] | 798 | "foobar" the package identifier, which was previously defined using the |
| 799 | |bindtextdomain()| function. |
| 800 | |
| 801 | After that you need to create a template file for translation - POT-file. |
| 802 | To do this, execute the following commands (using the Vim repository): > |
| 803 | cd ~/forkvim/src/po |
| 804 | make -f Makefile "PLUGPACKAGE={package}" \ |
| 805 | "PO_PLUG_INPUTLIST={path/to/scripts-that-need-translations.vim}" \ |
| 806 | ["POT_PLUGPACKAGE_PATH={path/where/to/write/{package}.pot}" \] |
| 807 | ["VIMPROG={path/to/vim} \] |
| 808 | {package}.pot |
| 809 | < |
| 810 | Where: |
| 811 | PLUGPACKAGE A variable containing the name of the package that we |
| 812 | specified in the |bindtextdomain()| and |
| 813 | |gettext()| functions, for example, "foobar". |
| 814 | PO_PLUG_INPUTLIST A variable containing scripts that have strings |
| 815 | to translate, i.e. where we specified the |gettext()| |
| 816 | function. Scripts are specified with an absolute |
| 817 | or relative path. Example: start/foobar/plugin/bar.vim |
| 818 | use blanks to separate scripts. |
| 819 | POT_PLUGPACKAGE_PATH A variable containing the directory where the prepared |
| 820 | POT file will be saved. This is not a required variable, |
| 821 | if no directory is specified, then the POT file will |
| 822 | be placed in the "src/po" directory. |
| 823 | VIMPROG A variable containing a directory with a working Vim. |
| 824 | If the Vim editor is already built and installed, and |
| 825 | is contained in the $PATH environment variable, |
| 826 | then you can specify just the name of the vim |
| 827 | executable. |
| 828 | {package}.pot This is the Target. It is specified as the name of |
| 829 | the package, for example, "foobar" with the addition |
| 830 | of the .pot extension. |
| 831 | Once a POT file is created, its contents are copied into separate PO files for |
| 832 | each language for which the translation will be prepared. |
| 833 | |
| 834 | When the translation is finished, it is necessary to convert the PO files into |
| 835 | binary MO-files format and place these MO-files into the "lang/" directory, the |
| 836 | structure of which we created earlier. |
| 837 | To do this, run the following commands: |
| 838 | > |
| 839 | cd ~/forkvim/src/po |
| 840 | make -f Makefile "PLUGPACKAGE={package}" \ |
| 841 | "PO_PLUGPACKAGE={path/to/{lang}.po}" \ |
| 842 | ["MO_PLUGPACKAGE_PATH={path/to/lang/<lang_id>/LC_MESSAGES}" \] |
| 843 | {package}.mo |
| 844 | < |
| 845 | Where: |
| 846 | PLUGPACKAGE A variable containing the name of the package that we |
| 847 | specified in the |bindtextdomain()| and |gettext()| |
| 848 | functions, for example, "foobar". |
| 849 | PO_PLUGPACKAGE A variable containing a PO file. The file is specified |
| 850 | with an absolute or relative path. For example, |
| 851 | "~/myproject/translate/en.po" |
| 852 | MO_PLUGPACKAGE_PATH A variable containing the structure of the "lang/" |
| 853 | directory, where the file with translations will be |
| 854 | placed, for example, "foobar.mo". This is not |
| 855 | a required variable, if the directory is not specified, |
| 856 | the MO file will be saved in the "src/po" directory. |
| 857 | {package}.mo This is the Target. It is specified as the name of |
| 858 | the package, for example, "foobar" with the addition |
| 859 | of the .mo extension. |
| 860 | |
| 861 | *package-translate_example* |
| 862 | Let's show it all on some concrete example and translate the |
| 863 | "ftplugin/aap.vim" file into Russian and German. |
| 864 | |
| 865 | First, let's prepare the "aap.vim" file, specifying |bindtextdomain()| and |
| 866 | |gettext()| function calls in it. |
| 867 | > |
| 868 | " Only do this when not done yet for this buffer |
| 869 | if exists("b:did_ftplugin") |
| 870 | finish |
| 871 | endif |
| 872 | |
| 873 | " Don't load another plugin for this buffer |
| 874 | let b:did_ftplugin = 1 |
| 875 | call bindtextdomain("aap", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/') |
| 876 | |
| 877 | " Reset 'formatoptions', 'comments', 'commentstring' and 'expandtab' to undo |
| 878 | " this plugin. |
| 879 | let b:undo_ftplugin = "setl fo< com< cms< et<" |
| 880 | |
| 881 | " Set 'formatoptions' to break comment lines but not other lines, |
| 882 | " and insert the comment leader when hitting <CR> or using "o". |
| 883 | setlocal fo-=t fo+=croql |
| 884 | |
| 885 | " Set 'comments' to format dashed lists in comments. |
| 886 | setlocal comments=s:#\ -,m:#\ \ ,e:#,n:#,fb:- |
| 887 | setlocal commentstring=#\ %s |
| 888 | |
| 889 | " Expand tabs to spaces to avoid trouble. |
| 890 | setlocal expandtab |
| 891 | |
| 892 | if (has("gui_win32") || has("gui_gtk")) && !exists("b:browsefilter") |
| 893 | let b:browsefilter = gettext("Aap Recipe Files (*.aap)\t*.aap\n", "aap") |
| 894 | if has("win32") |
| 895 | let b:browsefilter ..= gettext("All Files (*.*)\t*\n", "aap") |
| 896 | else |
| 897 | let b:browsefilter ..= gettext("All Files (*)\t*\n", "aap") |
| 898 | endif |
| 899 | let b:undo_ftplugin ..= " | unlet! b:browsefilter" |
| 900 | endif |
| 901 | < |
| 902 | Now let's create a POT file for it (example uses Windows paths): |
| 903 | > |
| 904 | cd /d f:\forkvim\src\po |
| 905 | (the following command must be entered in one line, here it is separated for example) |
| 906 | nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap" |
| 907 | "PO_PLUG_INPUTLIST=d:\Programs\vim\vim91\ftplugin\aap.vim" |
| 908 | "POT_PLUGPACKAGE_PATH=e:\project\translate\plugins" |
| 909 | "VIMPROG=d:\Programs\vim\vim91\vim.exe" |
| 910 | aap.pot |
| 911 | < |
| 912 | After the POT file of our package is created, go to the directory where we |
| 913 | saved it and perform the translation. |
| 914 | > |
| 915 | cd /d e:\project\translate\plugins |
| 916 | copy aap.pot ru.po |
| 917 | copy aap.pot de.po |
| 918 | < |
| 919 | We have prepared a PO file with a translation into Russian: |
| 920 | # Test plugins translate ~ |
| 921 | # ~ |
| 922 | msgid "" ~ |
| 923 | msgstr "" ~ |
| 924 | "Project-Id-Version: aap\n" ~ |
| 925 | "Report-Msgid-Bugs-To: \n" ~ |
| 926 | "POT-Creation-Date: 2024-06-23 14:58+0300\n" ~ |
| 927 | "PO-Revision-Date: 2024-06-23 14:58+0300\n" ~ |
| 928 | "Last-Translator: Restorer\n" ~ |
| 929 | "Language-Team: RuVim\n" ~ |
| 930 | "Language: ru\n" ~ |
| 931 | "MIME-Version: 1.0\n" ~ |
| 932 | "Content-Type: text/plain; charset=UTF-8\n" ~ |
| 933 | "Content-Transfer-Encoding: 8bit\n" ~ |
| 934 | |
| 935 | #: ../../runtime/ftplugin/aap.vim:32 ~ |
| 936 | msgid "Aap Recipe Files (*.aap)\t*.aap\n" ~ |
| 937 | msgstr "Файлы инструкций Aap (*.aap)\t*.aap\n" ~ |
| 938 | |
| 939 | #: ../../runtime/ftplugin/aap.vim:34 ~ |
| 940 | msgid "All Files (*.*)\t*\n" ~ |
| 941 | msgstr "Все файлы (*.*)\t*\n" ~ |
| 942 | |
| 943 | #: ../../runtime/ftplugin/aap.vim:36 ~ |
| 944 | msgid "All Files (*)\t*\n" ~ |
| 945 | msgstr "Все файлы (*)\t*\n" ~ |
| 946 | |
| 947 | And the PO file in German: |
| 948 | # Test plugins translate~ |
| 949 | #~ |
| 950 | msgid ""~ |
| 951 | msgstr ""~ |
| 952 | "Project-Id-Version: aap\n"~ |
| 953 | "Report-Msgid-Bugs-To: \n"~ |
| 954 | "POT-Creation-Date: 2024-06-23 14:58+0300\n"~ |
| 955 | "PO-Revision-Date: 2024-06-24 13:11+0300\n"~ |
| 956 | "Last-Translator: Restorer\n"~ |
| 957 | "Language-Team: German\n"~ |
| 958 | "Language: de\n"~ |
| 959 | "MIME-Version: 1.0\n"~ |
| 960 | "Content-Type: text/plain; charset=UTF-8\n"~ |
| 961 | "Content-Transfer-Encoding: 8bit\n"~ |
| 962 | |
| 963 | #: ../../runtime/ftplugin/aap.vim:32~ |
| 964 | msgid "Aap Recipe Files (*.aap)\t*.aap\n"~ |
| 965 | msgstr "Aap-Rezeptdateien (*.aap)\t*.aap\n"~ |
| 966 | |
| 967 | #: ../../runtime/ftplugin/aap.vim:34~ |
| 968 | msgid "All Files (*.*)\t*\n"~ |
| 969 | msgstr "Alle Dateien (*.*)\t*.*\n"~ |
| 970 | |
| 971 | #: ../../runtime/ftplugin/aap.vim:36~ |
| 972 | msgid "All Files (*)\t*\n"~ |
| 973 | msgstr "Alle Dateien (*)\t*\n"~ |
| 974 | |
| 975 | Now convert these files into MO files so that |gettext()| can display message |
| 976 | translations. Note that since this is not a specialized plugin package, we |
| 977 | will put the MO files in the "lang/" directory of the Vim editor. |
| 978 | Type the following commands: |
| 979 | > |
| 980 | cd /d f:\forkvim\src\po |
Milly | 89872f5 | 2024-10-05 17:16:18 +0200 | [diff] [blame] | 981 | < (the following command must be entered in one line, here it is separated for example) |
| 982 | For Russian: > |
RestorerZ | 9650910 | 2024-07-11 21:14:15 +0200 | [diff] [blame] | 983 | nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap" |
| 984 | "PO_PLUGPACKAGE=e:\project\translate\plugins\ru.po" |
| 985 | "MO_PLUGPACKAGE_PATH=d:\Programs\vim\vim91\lang\ru\LC_MESSAGES" |
| 986 | aap.mo |
Milly | 89872f5 | 2024-10-05 17:16:18 +0200 | [diff] [blame] | 987 | < For German: > |
RestorerZ | 9650910 | 2024-07-11 21:14:15 +0200 | [diff] [blame] | 988 | nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap" |
| 989 | "PO_PLUGPACKAGE=e:\project\translate\plugins\de.po" |
| 990 | "MO_PLUGPACKAGE_PATH=d:\Programs\vim\vim91\lang\de\LC_MESSAGES" |
| 991 | aap.mo |
| 992 | < |
| 993 | That's it, the translations are ready and you can see the plugin's messages |
| 994 | in your native language. |
| 995 | |
| 996 | Let's also try to translate a plugin package. For example, when a package |
| 997 | contains several scripts containing strings that need to be translated. |
| 998 | For example, let's translate the "netrw" package into Japanese. |
| 999 | For this example, we will translate only a few lines from this package. |
| 1000 | Let's prepare the scripts where we need to translate the message strings. |
| 1001 | |
| 1002 | The file "autoload\netrw.vim": |
| 1003 | > |
| 1004 | " Load Once: |
| 1005 | if &cp || exists("g:loaded_netrw") |
| 1006 | finish |
| 1007 | endif |
| 1008 | call bindtextdomain("netrw", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/') |
| 1009 | |
| 1010 | " Check that vim has patches that netrw requires. |
| 1011 | " Patches needed for v7.4: 1557, and 213. |
| 1012 | " (netrw will benefit from vim's having patch#656, too) |
| 1013 | let s:needspatches=[1557,213] |
| 1014 | if exists("s:needspatches") |
| 1015 | for ptch in s:needspatches |
| 1016 | if v:version < 704 || (v:version == 704 && !has("patch".ptch)) |
| 1017 | if !exists("s:needpatch{ptch}") |
| 1018 | unsilent echomsg gettext("***sorry*** this version of netrw requires vim v7.4 with patch#", "netrw") .. ptch |
| 1019 | endif |
| 1020 | let s:needpatch{ptch}= 1 |
| 1021 | finish |
| 1022 | endif |
| 1023 | endfor |
| 1024 | endif |
| 1025 | < |
| 1026 | The file "autoload\netrwSettings.vim": |
| 1027 | > |
| 1028 | " Load Once: |
| 1029 | if exists("g:loaded_netrwSettings") || &cp |
| 1030 | finish |
| 1031 | endif |
| 1032 | call bindtextdomain("netrw", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/') |
| 1033 | let g:loaded_netrwSettings = "v18" |
| 1034 | if v:version < 700 |
| 1035 | echohl WarningMsg |
| 1036 | echo gettext("***warning*** this version of netrwSettings needs vim 7.0", "netrw") |
| 1037 | echohl Normal |
| 1038 | finish |
| 1039 | endif |
| 1040 | < |
| 1041 | Now we will prepare a POT file for further translation of messages. |
| 1042 | Execute the following commands: |
| 1043 | > |
| 1044 | cd ~/forkvim/src/po |
| 1045 | make -f Makefile "VIMPROG=/usr/local/bin/vim" "PLUGPACKAGE=netrw" \ |
| 1046 | "POT_PLUGPACKAGE_PATH=~/project/translate/plugins" \ |
| 1047 | "PO_PLUG_INPUTLIST=../../runtime/autoload/netrw.vim |
| 1048 | ../../runtime/autoload/netrwSettings.vim" \ |
| 1049 | netrw.pot |
| 1050 | < |
| 1051 | Go to the directory with the POT file and make the translation: |
| 1052 | > |
| 1053 | cd ~/project/translate/plugins |
| 1054 | cp ./netrw.pot ja.po |
| 1055 | < |
| 1056 | When we have the translation ready in the "ja.po" file: |
| 1057 | # Test plugins translate ~ |
| 1058 | # ~ |
| 1059 | msgid "" ~ |
| 1060 | msgstr "" ~ |
| 1061 | "Project-Id-Version: netrw\n" ~ |
| 1062 | "Report-Msgid-Bugs-To: \n" ~ |
| 1063 | "POT-Creation-Date: 2024-06-23 17:14+0300\n" ~ |
| 1064 | "PO-Revision-Date: 2024-06-23 17:14+0300\n" ~ |
| 1065 | "Last-Translator: Restorer\n" ~ |
| 1066 | "Language-Team: Japanese\n" ~ |
| 1067 | "Language: ja\n" ~ |
| 1068 | "MIME-Version: 1.0\n" ~ |
| 1069 | "Content-Type: text/plain; charset=UTF-8\n" ~ |
| 1070 | "Content-Transfer-Encoding: 8bit\n" ~ |
| 1071 | |
| 1072 | #: ../../runtime/autoload/netrw.vim:51 ~ |
| 1073 | msgid "***sorry*** this version of netrw requires vim v7.4 with patch#" ~ |
| 1074 | msgstr "" ~ |
| 1075 | "***申し訳ありません***このバージョンのnetrwには、パッチ付きのvim v7.4が必要です#" ~ |
| 1076 | |
| 1077 | #: ../../runtime/autoload/netrwSettings.vim:28 ~ |
| 1078 | msgid "***warning*** this version of netrwSettings needs vim 7.0" ~ |
| 1079 | msgstr "***警告***このバージョンのnetrwSettingsにはvim7.0が必要です" ~ |
| 1080 | |
| 1081 | Convert ja.po to a MO file: |
| 1082 | > |
| 1083 | cd ~/forkvim/src/po |
| 1084 | make -f Makefile "PLUGPACKAGE=netrw" \ |
| 1085 | "PO_PLUGPACKAGE=~/project/translate/plugins/ja.po" \ |
| 1086 | "MO_PLUGPACKAGE_PATH=/usr/local/share/vim/vim91/lang/ja/LC_MESSAGES" \ |
| 1087 | netrw.mo |
| 1088 | < |
| 1089 | Executing those steps will allow you to get translation of any third-party |
| 1090 | plug-in packages. |
Bram Moolenaar | 03413f4 | 2016-04-12 21:07:15 +0200 | [diff] [blame] | 1091 | |
| 1092 | Dependencies between plugins ~ |
| 1093 | *packload-two-steps* |
Bram Moolenaar | c95a302 | 2016-06-12 23:01:46 +0200 | [diff] [blame] | 1094 | Suppose you have two plugins that depend on the same functionality. You can |
Bram Moolenaar | 03413f4 | 2016-04-12 21:07:15 +0200 | [diff] [blame] | 1095 | put the common functionality in an autoload directory, so that it will be |
| 1096 | found automatically. Your package would have these files: |
| 1097 | |
| 1098 | pack/foo/start/one/plugin/one.vim > |
| 1099 | call foolib#getit() |
| 1100 | < pack/foo/start/two/plugin/two.vim > |
| 1101 | call foolib#getit() |
| 1102 | < pack/foo/start/lib/autoload/foolib.vim > |
| 1103 | func foolib#getit() |
| 1104 | |
| 1105 | This works, because loading packages will first add all found directories to |
| 1106 | 'runtimepath' before sourcing the plugins. |
| 1107 | |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 1108 | ============================================================================== |
| 1109 | 7. Debugging scripts *debug-scripts* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1110 | |
| 1111 | Besides the obvious messages that you can add to your scripts to find out what |
| 1112 | they are doing, Vim offers a debug mode. This allows you to step through a |
| 1113 | sourced file or user function and set breakpoints. |
| 1114 | |
| 1115 | NOTE: The debugging mode is far from perfect. Debugging will have side |
| 1116 | effects on how Vim works. You cannot use it to debug everything. For |
| 1117 | example, the display is messed up by the debugging messages. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1118 | |
| 1119 | An alternative to debug mode is setting the 'verbose' option. With a bigger |
| 1120 | number it will give more verbose messages about what Vim is doing. |
| 1121 | |
| 1122 | |
| 1123 | STARTING DEBUG MODE *debug-mode* |
| 1124 | |
| 1125 | To enter debugging mode use one of these methods: |
| 1126 | 1. Start Vim with the |-D| argument: > |
| 1127 | vim -D file.txt |
| 1128 | < Debugging will start as soon as the first vimrc file is sourced. This is |
| 1129 | useful to find out what is happening when Vim is starting up. A side |
| 1130 | effect is that Vim will switch the terminal mode before initialisations |
| 1131 | have finished, with unpredictable results. |
| 1132 | For a GUI-only version (Windows, Macintosh) the debugging will start as |
| 1133 | soon as the GUI window has been opened. To make this happen early, add a |
| 1134 | ":gui" command in the vimrc file. |
| 1135 | *:debug* |
| 1136 | 2. Run a command with ":debug" prepended. Debugging will only be done while |
| 1137 | this command executes. Useful for debugging a specific script or user |
| 1138 | function. And for scripts and functions used by autocommands. Example: > |
| 1139 | :debug edit test.txt.gz |
| 1140 | |
| 1141 | 3. Set a breakpoint in a sourced file or user function. You could do this in |
| 1142 | the command line: > |
| 1143 | vim -c "breakadd file */explorer.vim" . |
| 1144 | < This will run Vim and stop in the first line of the "explorer.vim" script. |
| 1145 | Breakpoints can also be set while in debugging mode. |
| 1146 | |
| 1147 | In debugging mode every executed command is displayed before it is executed. |
| 1148 | Comment lines, empty lines and lines that are not executed are skipped. When |
| 1149 | a line contains two commands, separated by "|", each command will be displayed |
| 1150 | separately. |
| 1151 | |
| 1152 | |
| 1153 | DEBUG MODE |
| 1154 | |
| 1155 | Once in debugging mode, the usual Ex commands can be used. For example, to |
| 1156 | inspect the value of a variable: > |
| 1157 | echo idx |
| 1158 | When inside a user function, this will print the value of the local variable |
| 1159 | "idx". Prepend "g:" to get the value of a global variable: > |
| 1160 | echo g:idx |
| 1161 | All commands are executed in the context of the current function or script. |
| 1162 | You can also set options, for example setting or resetting 'verbose' will show |
| 1163 | what happens, but you might want to set it just before executing the lines you |
| 1164 | are interested in: > |
| 1165 | :set verbose=20 |
| 1166 | |
| 1167 | Commands that require updating the screen should be avoided, because their |
| 1168 | effect won't be noticed until after leaving debug mode. For example: > |
| 1169 | :help |
| 1170 | won't be very helpful. |
| 1171 | |
| 1172 | There is a separate command-line history for debug mode. |
| 1173 | |
Bram Moolenaar | 6304be6 | 2021-11-27 10:57:26 +0000 | [diff] [blame] | 1174 | NOTE: In Vim9 script, if a command is written at the script level and |
| 1175 | continues on the next line, not using the old way with a backslash for line |
| 1176 | continuation, only the first line is printed before the debugging prompt. |
| 1177 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1178 | The line number for a function line is relative to the start of the function. |
| 1179 | If you have trouble figuring out where you are, edit the file that defines |
| 1180 | the function in another Vim, search for the start of the function and do |
| 1181 | "99j". Replace "99" with the line number. |
| 1182 | |
| 1183 | Additionally, these commands can be used: |
| 1184 | *>cont* |
| 1185 | cont Continue execution until the next breakpoint is hit. |
| 1186 | *>quit* |
| 1187 | quit Abort execution. This is like using CTRL-C, some |
| 1188 | things might still be executed, doesn't abort |
| 1189 | everything. Still stops at the next breakpoint. |
| 1190 | *>next* |
| 1191 | next Execute the command and come back to debug mode when |
| 1192 | it's finished. This steps over user function calls |
| 1193 | and sourced files. |
| 1194 | *>step* |
| 1195 | step Execute the command and come back to debug mode for |
| 1196 | the next command. This steps into called user |
| 1197 | functions and sourced files. |
| 1198 | *>interrupt* |
| 1199 | interrupt This is like using CTRL-C, but unlike ">quit" comes |
| 1200 | back to debug mode for the next command that is |
| 1201 | executed. Useful for testing |:finally| and |:catch| |
| 1202 | on interrupt exceptions. |
| 1203 | *>finish* |
| 1204 | finish Finish the current script or user function and come |
| 1205 | back to debug mode for the command after the one that |
| 1206 | sourced or called it. |
Bram Moolenaar | f1f60f8 | 2016-01-16 15:40:53 +0100 | [diff] [blame] | 1207 | *>bt* |
| 1208 | *>backtrace* |
| 1209 | *>where* |
| 1210 | backtrace Show the call stacktrace for current debugging session. |
| 1211 | bt |
| 1212 | where |
| 1213 | *>frame* |
Bram Moolenaar | 38a5563 | 2016-02-15 22:07:32 +0100 | [diff] [blame] | 1214 | frame N Goes to N backtrace level. + and - signs make movement |
Bram Moolenaar | f1f60f8 | 2016-01-16 15:40:53 +0100 | [diff] [blame] | 1215 | relative. E.g., ":frame +3" goes three frames up. |
| 1216 | *>up* |
| 1217 | up Goes one level up from call stacktrace. |
| 1218 | *>down* |
| 1219 | down Goes one level down from call stacktrace. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1220 | |
| 1221 | About the additional commands in debug mode: |
| 1222 | - There is no command-line completion for them, you get the completion for the |
| 1223 | normal Ex commands only. |
Bram Moolenaar | dae8d21 | 2016-02-27 22:40:16 +0100 | [diff] [blame] | 1224 | - You can shorten them, up to a single character, unless more than one command |
Bram Moolenaar | f1f60f8 | 2016-01-16 15:40:53 +0100 | [diff] [blame] | 1225 | starts with the same letter. "f" stands for "finish", use "fr" for "frame". |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1226 | - Hitting <CR> will repeat the previous one. When doing another command, this |
| 1227 | is reset (because it's not clear what you want to repeat). |
| 1228 | - When you want to use the Ex command with the same name, prepend a colon: |
| 1229 | ":cont", ":next", ":finish" (or shorter). |
Bram Moolenaar | 4d8f476 | 2021-06-27 15:18:56 +0200 | [diff] [blame] | 1230 | *vim9-debug* |
| 1231 | When debugging a compiled :def function, "step" will stop before every |
Bram Moolenaar | 90df4b9 | 2021-07-07 20:26:08 +0200 | [diff] [blame] | 1232 | executed line, not every single instruction. Thus it works mostly like a not |
Bram Moolenaar | 4d8f476 | 2021-06-27 15:18:56 +0200 | [diff] [blame] | 1233 | compiled function. Access to local variables is limited you can use: > |
| 1234 | echo varname |
| 1235 | But not much else. |
| 1236 | When executing a command that is not a specific bytecode instruction but |
| 1237 | executed like a normal Ex command, "step" will stop once in the compiled |
| 1238 | context, where local variables can be inspected, and once just before |
| 1239 | executing the command. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1240 | |
Bram Moolenaar | 9fbdbb8 | 2022-09-27 17:30:34 +0100 | [diff] [blame] | 1241 | In a :def function variables that haven't been declared yet cannot be |
| 1242 | inspected. Variables that have been declared can be inspected, also when the |
| 1243 | block they were declared in has finished. In commands this would not be |
| 1244 | possible, thus is slightly misleading (but can be useful). |
| 1245 | |
Bram Moolenaar | f1f60f8 | 2016-01-16 15:40:53 +0100 | [diff] [blame] | 1246 | The backtrace shows the hierarchy of function calls, e.g.: |
| 1247 | >bt ~ |
| 1248 | 3 function One[3] ~ |
| 1249 | 2 Two[3] ~ |
| 1250 | ->1 Three[3] ~ |
| 1251 | 0 Four ~ |
| 1252 | line 1: let four = 4 ~ |
| 1253 | |
| 1254 | The "->" points to the current frame. Use "up", "down" and "frame N" to |
| 1255 | select another frame. |
| 1256 | |
| 1257 | In the current frame you can evaluate the local function variables. There is |
| 1258 | no way to see the command at the current line yet. |
| 1259 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1260 | |
| 1261 | DEFINING BREAKPOINTS |
| 1262 | *:breaka* *:breakadd* |
| 1263 | :breaka[dd] func [lnum] {name} |
| 1264 | Set a breakpoint in a function. Example: > |
| 1265 | :breakadd func Explore |
| 1266 | < Doesn't check for a valid function name, thus the breakpoint |
| 1267 | can be set before the function is defined. |
| 1268 | |
| 1269 | :breaka[dd] file [lnum] {name} |
| 1270 | Set a breakpoint in a sourced file. Example: > |
| 1271 | :breakadd file 43 .vimrc |
| 1272 | |
Bram Moolenaar | f4b8e57 | 2004-06-24 15:53:16 +0000 | [diff] [blame] | 1273 | :breaka[dd] here |
| 1274 | Set a breakpoint in the current line of the current file. |
| 1275 | Like doing: > |
| 1276 | :breakadd file <cursor-line> <current-file> |
| 1277 | < Note that this only works for commands that are executed when |
| 1278 | sourcing the file, not for a function defined in that file. |
| 1279 | |
Bram Moolenaar | c6f9f73 | 2018-02-11 19:06:26 +0100 | [diff] [blame] | 1280 | :breaka[dd] expr {expression} |
| 1281 | Sets a breakpoint, that will break whenever the {expression} |
| 1282 | evaluates to a different value. Example: > |
| 1283 | :breakadd expr g:lnum |
Bram Moolenaar | c6f9f73 | 2018-02-11 19:06:26 +0100 | [diff] [blame] | 1284 | < Will break, whenever the global variable lnum changes. |
Bram Moolenaar | 6c391a7 | 2021-09-09 21:55:11 +0200 | [diff] [blame] | 1285 | |
| 1286 | Errors in evaluation are suppressed, you can use the name of a |
| 1287 | variable that does not exist yet. This also means you will |
| 1288 | not notice anything if the expression has a mistake. |
| 1289 | |
Bram Moolenaar | c6f9f73 | 2018-02-11 19:06:26 +0100 | [diff] [blame] | 1290 | Note if you watch a |script-variable| this will break |
| 1291 | when switching scripts, since the script variable is only |
| 1292 | valid in the script where it has been defined and if that |
| 1293 | script is called from several other scripts, this will stop |
| 1294 | whenever that particular variable will become visible or |
Bram Moolenaar | 9faec4e | 2021-02-27 16:38:07 +0100 | [diff] [blame] | 1295 | inaccessible again. |
Bram Moolenaar | c6f9f73 | 2018-02-11 19:06:26 +0100 | [diff] [blame] | 1296 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1297 | The [lnum] is the line number of the breakpoint. Vim will stop at or after |
| 1298 | this line. When omitted line 1 is used. |
| 1299 | |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1300 | *:debug-name* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1301 | {name} is a pattern that is matched with the file or function name. The |
| 1302 | pattern is like what is used for autocommands. There must be a full match (as |
| 1303 | if the pattern starts with "^" and ends in "$"). A "*" matches any sequence |
| 1304 | of characters. 'ignorecase' is not used, but "\c" can be used in the pattern |
| 1305 | to ignore case |/\c|. Don't include the () for the function name! |
| 1306 | |
Bram Moolenaar | 843ee41 | 2004-06-30 16:16:41 +0000 | [diff] [blame] | 1307 | The match for sourced scripts is done against the full file name. If no path |
| 1308 | is specified the current directory is used. Examples: > |
| 1309 | breakadd file explorer.vim |
| 1310 | matches "explorer.vim" in the current directory. > |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1311 | breakadd file *explorer.vim |
Bram Moolenaar | 843ee41 | 2004-06-30 16:16:41 +0000 | [diff] [blame] | 1312 | matches ".../plugin/explorer.vim", ".../plugin/iexplorer.vim", etc. > |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1313 | breakadd file */explorer.vim |
Bram Moolenaar | 843ee41 | 2004-06-30 16:16:41 +0000 | [diff] [blame] | 1314 | matches ".../plugin/explorer.vim" and "explorer.vim" in any other directory. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1315 | |
| 1316 | The match for functions is done against the name as it's shown in the output |
Bram Moolenaar | b204990 | 2021-01-24 12:53:53 +0100 | [diff] [blame] | 1317 | of ":function". However, for local functions the script-specific prefix such |
| 1318 | as "<SNR>99_" is ignored to make it easier to match script-local functions |
| 1319 | without knowing the ID of the script. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1320 | |
Bram Moolenaar | 2ce06f6 | 2005-01-31 19:19:04 +0000 | [diff] [blame] | 1321 | Note that functions are first loaded and later executed. When they are loaded |
| 1322 | the "file" breakpoints are checked, when they are executed the "func" |
| 1323 | breakpoints. |
| 1324 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1325 | |
| 1326 | DELETING BREAKPOINTS |
| 1327 | *:breakd* *:breakdel* *E161* |
| 1328 | :breakd[el] {nr} |
| 1329 | Delete breakpoint {nr}. Use |:breaklist| to see the number of |
| 1330 | each breakpoint. |
| 1331 | |
Bram Moolenaar | f461c8e | 2005-06-25 23:04:51 +0000 | [diff] [blame] | 1332 | :breakd[el] * |
| 1333 | Delete all breakpoints. |
| 1334 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1335 | :breakd[el] func [lnum] {name} |
| 1336 | Delete a breakpoint in a function. |
| 1337 | |
| 1338 | :breakd[el] file [lnum] {name} |
| 1339 | Delete a breakpoint in a sourced file. |
| 1340 | |
Bram Moolenaar | f4b8e57 | 2004-06-24 15:53:16 +0000 | [diff] [blame] | 1341 | :breakd[el] here |
| 1342 | Delete a breakpoint at the current line of the current file. |
| 1343 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1344 | When [lnum] is omitted, the first breakpoint in the function or file is |
| 1345 | deleted. |
| 1346 | The {name} must be exactly the same as what was typed for the ":breakadd" |
| 1347 | command. "explorer", "*explorer.vim" and "*explorer*" are different. |
| 1348 | |
| 1349 | |
| 1350 | LISTING BREAKPOINTS |
| 1351 | *:breakl* *:breaklist* |
| 1352 | :breakl[ist] |
| 1353 | List all breakpoints. |
| 1354 | |
| 1355 | |
| 1356 | OBSCURE |
| 1357 | |
| 1358 | *:debugg* *:debuggreedy* |
| 1359 | :debugg[reedy] |
| 1360 | Read debug mode commands from the normal input stream, instead |
| 1361 | of getting them directly from the user. Only useful for test |
| 1362 | scripts. Example: > |
| 1363 | echo 'q^Mq' | vim -e -s -c debuggreedy -c 'breakadd file script.vim' -S script.vim |
| 1364 | |
| 1365 | :0debugg[reedy] |
| 1366 | Undo ":debuggreedy": get debug mode commands directly from the |
| 1367 | user, don't use typeahead for debug commands. |
| 1368 | |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1369 | ============================================================================== |
Bram Moolenaar | 4f3f668 | 2016-03-26 23:01:59 +0100 | [diff] [blame] | 1370 | 8. Profiling *profile* *profiling* |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1371 | |
Bram Moolenaar | 996343d | 2010-07-04 22:20:21 +0200 | [diff] [blame] | 1372 | Profiling means that Vim measures the time that is spent on executing |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1373 | functions and/or scripts. The |+profile| feature is required for this. |
Bram Moolenaar | b204990 | 2021-01-24 12:53:53 +0100 | [diff] [blame] | 1374 | It is included when Vim was compiled with "huge" features. |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1375 | |
Bram Moolenaar | 433f7c8 | 2006-03-21 21:29:36 +0000 | [diff] [blame] | 1376 | You can also use the |reltime()| function to measure time. This only requires |
Bram Moolenaar | b204990 | 2021-01-24 12:53:53 +0100 | [diff] [blame] | 1377 | the |+reltime| feature, which is present in more builds. |
Bram Moolenaar | 433f7c8 | 2006-03-21 21:29:36 +0000 | [diff] [blame] | 1378 | |
Bram Moolenaar | 16ea367 | 2013-07-28 16:02:18 +0200 | [diff] [blame] | 1379 | For profiling syntax highlighting see |:syntime|. |
| 1380 | |
Bram Moolenaar | 76f3b1a | 2014-03-27 22:30:07 +0100 | [diff] [blame] | 1381 | For example, to profile the one_script.vim script file: > |
| 1382 | :profile start /tmp/one_script_profile |
| 1383 | :profile file one_script.vim |
| 1384 | :source one_script.vim |
| 1385 | :exit |
| 1386 | |
Bram Moolenaar | 16ea367 | 2013-07-28 16:02:18 +0200 | [diff] [blame] | 1387 | |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1388 | :prof[ile] start {fname} *:prof* *:profile* *E750* |
Yegappan Lakshmanan | 18ee0f6 | 2022-04-08 13:23:19 +0100 | [diff] [blame] | 1389 | Start profiling, write the output in {fname} upon exit or when |
| 1390 | a `:profile stop` or `:profile dump` command is invoked. |
Bram Moolenaar | 0a63ded | 2015-04-15 13:31:24 +0200 | [diff] [blame] | 1391 | "~/" and environment variables in {fname} will be expanded. |
Bram Moolenaar | 9b2200a | 2006-03-20 21:55:45 +0000 | [diff] [blame] | 1392 | If {fname} already exists it will be silently overwritten. |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1393 | The variable |v:profiling| is set to one. |
| 1394 | |
Yegappan Lakshmanan | 18ee0f6 | 2022-04-08 13:23:19 +0100 | [diff] [blame] | 1395 | :prof[ile] stop |
| 1396 | Write the collected profiling information to the logfile and |
| 1397 | stop profiling. You can use the `:profile start` command to |
| 1398 | clear the profiling statistics and start profiling again. |
| 1399 | |
Bram Moolenaar | 9b2200a | 2006-03-20 21:55:45 +0000 | [diff] [blame] | 1400 | :prof[ile] pause |
Christian Brabandt | 4bfb899 | 2024-10-16 21:58:17 +0200 | [diff] [blame] | 1401 | Stop profiling until the next `:profile continue` command. |
| 1402 | Can be used when doing something that should not be counted |
| 1403 | (e.g., an external command). Does not nest. |
Bram Moolenaar | 9b2200a | 2006-03-20 21:55:45 +0000 | [diff] [blame] | 1404 | |
| 1405 | :prof[ile] continue |
Yegappan Lakshmanan | 18ee0f6 | 2022-04-08 13:23:19 +0100 | [diff] [blame] | 1406 | Continue profiling after `:profile pause`. |
Bram Moolenaar | 9b2200a | 2006-03-20 21:55:45 +0000 | [diff] [blame] | 1407 | |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1408 | :prof[ile] func {pattern} |
| 1409 | Profile function that matches the pattern {pattern}. |
| 1410 | See |:debug-name| for how {pattern} is used. |
| 1411 | |
| 1412 | :prof[ile][!] file {pattern} |
| 1413 | Profile script file that matches the pattern {pattern}. |
| 1414 | See |:debug-name| for how {pattern} is used. |
| 1415 | This only profiles the script itself, not the functions |
| 1416 | defined in it. |
| 1417 | When the [!] is added then all functions defined in the script |
Bram Moolenaar | 76f3b1a | 2014-03-27 22:30:07 +0100 | [diff] [blame] | 1418 | will also be profiled. |
| 1419 | Note that profiling only starts when the script is loaded |
| 1420 | after this command. A :profile command in the script itself |
| 1421 | won't work. |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1422 | |
Yegappan Lakshmanan | 18ee0f6 | 2022-04-08 13:23:19 +0100 | [diff] [blame] | 1423 | :prof[ile] dump |
| 1424 | Write the current state of profiling to the logfile |
| 1425 | immediately. After running this command, Vim continues to |
| 1426 | collect the profiling statistics. |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1427 | |
Bram Moolenaar | d9fba31 | 2005-06-26 22:34:35 +0000 | [diff] [blame] | 1428 | :profd[el] ... *:profd* *:profdel* |
| 1429 | Stop profiling for the arguments specified. See |:breakdel| |
Yegappan Lakshmanan | 18ee0f6 | 2022-04-08 13:23:19 +0100 | [diff] [blame] | 1430 | for the arguments. Examples: > |
| 1431 | profdel func MyFunc |
| 1432 | profdel file MyScript.vim |
| 1433 | profdel here |
Bram Moolenaar | d9fba31 | 2005-06-26 22:34:35 +0000 | [diff] [blame] | 1434 | |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1435 | You must always start with a ":profile start fname" command. The resulting |
Bram Moolenaar | b204990 | 2021-01-24 12:53:53 +0100 | [diff] [blame] | 1436 | file is written when Vim exits. For example, to profile one specific |
| 1437 | function: > |
| 1438 | profile start /tmp/vimprofile |
| 1439 | profile func MyFunc |
| 1440 | |
| 1441 | Here is an example of the output, with line |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1442 | numbers prepended for the explanation: |
| 1443 | |
| 1444 | 1 FUNCTION Test2() ~ |
| 1445 | 2 Called 1 time ~ |
| 1446 | 3 Total time: 0.155251 ~ |
| 1447 | 4 Self time: 0.002006 ~ |
| 1448 | 5 ~ |
| 1449 | 6 count total (s) self (s) ~ |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 1450 | 7 9 0.000096 for i in range(8) ~ |
| 1451 | 8 8 0.153655 0.000410 call Test3() ~ |
| 1452 | 9 8 0.000070 endfor ~ |
| 1453 | 10 " Ask a question ~ |
| 1454 | 11 1 0.001341 echo input("give me an answer: ") ~ |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1455 | |
| 1456 | The header (lines 1-4) gives the time for the whole function. The "Total" |
| 1457 | time is the time passed while the function was executing. The "Self" time is |
| 1458 | the "Total" time reduced by time spent in: |
| 1459 | - other user defined functions |
| 1460 | - sourced scripts |
| 1461 | - executed autocommands |
| 1462 | - external (shell) commands |
| 1463 | |
| 1464 | Lines 7-11 show the time spent in each executed line. Lines that are not |
| 1465 | executed do not count. Thus a comment line is never counted. |
| 1466 | |
| 1467 | The Count column shows how many times a line was executed. Note that the |
| 1468 | "for" command in line 7 is executed one more time as the following lines. |
| 1469 | That is because the line is also executed to detect the end of the loop. |
| 1470 | |
| 1471 | The time Vim spends waiting for user input isn't counted at all. Thus how |
| 1472 | long you take to respond to the input() prompt is irrelevant. |
| 1473 | |
| 1474 | Profiling should give a good indication of where time is spent, but keep in |
| 1475 | mind there are various things that may clobber the results: |
| 1476 | |
Ernie Rael | 076de79 | 2023-03-16 21:43:15 +0000 | [diff] [blame] | 1477 | - The accuracy of the time measured depends on the gettimeofday(), or |
h_east | ba77bbb | 2023-10-03 04:47:13 +0900 | [diff] [blame] | 1478 | clock_gettime() if available, system function. The accuracy ranges from |
| 1479 | 1/100 second to nanoseconds. With clock_gettime() the times are displayed in |
Bram Moolenaar | 71badf9 | 2023-04-22 22:40:14 +0100 | [diff] [blame] | 1480 | nanoseconds, otherwise microseconds. You can use `has("prof_nsec")`. |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1481 | |
| 1482 | - Real elapsed time is measured, if other processes are busy they may cause |
| 1483 | delays at unpredictable moments. You may want to run the profiling several |
| 1484 | times and use the lowest results. |
| 1485 | |
| 1486 | - If you have several commands in one line you only get one time. Split the |
| 1487 | line to see the time for the individual commands. |
| 1488 | |
| 1489 | - The time of the lines added up is mostly less than the time of the whole |
| 1490 | function. There is some overhead in between. |
| 1491 | |
| 1492 | - Functions that are deleted before Vim exits will not produce profiling |
| 1493 | information. You can check the |v:profiling| variable if needed: > |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 1494 | :if !v:profiling |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1495 | : delfunc MyFunc |
| 1496 | :endif |
| 1497 | < |
Bram Moolenaar | 8cd06ca | 2005-02-28 22:44:58 +0000 | [diff] [blame] | 1498 | - Profiling may give weird results on multi-processor systems, when sleep |
| 1499 | mode kicks in or the processor frequency is reduced to save power. |
Bram Moolenaar | 05159a0 | 2005-02-26 23:04:13 +0000 | [diff] [blame] | 1500 | |
Bram Moolenaar | c81e5e7 | 2007-05-05 18:24:42 +0000 | [diff] [blame] | 1501 | - The "self" time is wrong when a function is used recursively. |
| 1502 | |
| 1503 | |
Bram Moolenaar | 91f84f6 | 2018-07-29 15:07:52 +0200 | [diff] [blame] | 1504 | vim:tw=78:ts=8:noet:ft=help:norl: |