vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

repeat.txt (59278B)


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