{"owner":"macvim-dev","repo":"macvim","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nGuidance for AI coding agents working in the Vim repository.\n\n## Project\n\nVim is a text editor written in C. The canonical repository is\nhttps://github.com/vim/vim. The code is old and has grown organically over\nthe past 30+ years. Some files are vendored from upstream projects\n(`src/xdiff`, `src/libvterm`); parts of the runtime are occasionally shared\nwith forks like Neovim.\n\nVim strives to be portable across several different operating systems and\naims to be a stable, robust editor gradually developing new features while\nremaining backwards compatible as much as possible.\n\nAt the same time, Vim can be compiled with different feature sets, from the\nPOSIX compatible minimal vi to a full-fledged GUI editor which includes\nadditional scripting interfaces.\n\nSee `runtime/doc/develop.txt` for the high level design goals.\n\n## Build and test\n\n    # Full build on Unix/Linux (from src/):\n    make\n\n    # Run the full test suite:\n    make test\n\n    # Generate proto files\n    make proto\n\n    # Run a single test file:\n    cd src/testdir && make test_name.res\n\nOutput is in testdir/messages and testdir/test.log\n\nBuilds on Windows depend on the Environment, see `src/INSTALLpc.txt`\nfor Cygwin/MSYS and MSVC ways to build Vim\n\nBefore submitting any patch, at minimum:\n1. The build succeeds without new warnings.\n2. Relevant tests pass.\n3. The code matches the style of the file being edited.\n\n## Layout\n\n- `src/` - the C source. Subsystem names are usually obvious from filenames\n  (`buffer.c`, `window.c`, `search.c`, `vim9compile.c`, etc.).\n- `src/proto/` - function prototypes, one `.pro` file per source file.\n  Regenerated; do not hand-edit unless you know what you're doing.\n- `src/po` - Translations\n- `src/xxd` - for the xxd subproject\n- `src/xdiff` - for the xdiff library (imported from git)\n- `src/libvterm` - for the libvterm library\n- `src/testdir/` - tests. Vim-script files named `test_*.vim`.\n  Screendump expected output lives in `src/testdir/dumps/`.\n- `runtime/doc/` - user-facing documentation in Vim help format, when updating,\n  also update the Last Change header\n- `runtime/syntax/generator` - Syntax script for Vim Script, automatically generated\n  from Vims source\n- `runtime/`  - runtime files shipped with Vim, when updating, also update the\n  Last Change header and a short description if this file has no maintainer\n  If the file has a maintainer, changes should go via them (so make a merge\n  request against the upstream repo instead)\n- `src/version.c` - contains the `included_patches[]` list. Every\n  patch touching anything below `src/` (with the exception of `src/po`) needs a\n  new entry at the top, will be updated only when merging into\n  the master tree.\n\n## Commit format\n\nVim uses a strict commit message format. The subject line is a\none-sentence **problem statement**, not a description of the fix:\n\n    patch 9.2.NNNN: short description of the problem\n\n    Problem:  Restatement of the problem as a full sentence, possibly\n              with a reporter attribution in parentheses.\n    Solution: Short description of the fix, ending with the author's\n              name in parentheses.\n\n    optional longer description of the problem and solution goes here in prose.\n    Do not use bullet points.\n\n    fixes:   #NNNN\n    related: #NNNN\n    closes:  #NNNN\n\n    Co-authored-by: Name\n    Signed-off-by: Author Name <email>\n\nRules:\n\n- **Subject line states the problem**, not the solution. \"fix typo\" is\n  wrong; \"typo in foo() causes OOB read\" is right.\n- **Problem line is a full sentence with a trailing period.** It mirrors\n  the subject.\n- **Solution line ends with `(Author Name)`** — parentheses, period\n  after them.\n- **Longer prose**, if any, goes after the Problem/Solution header\n- **`fixes:` references the issue** the patch fixes.\n  **`closes:` references the PR** that introduces the fix.\n  **`related:` references related issues**, including issues that caused this\n  one.\n  All can appear. Colon, aligned, no trailing period.\n- **`Signed-off-by:` is required** — DCO.\n- **`Co-Authored-By:` is allowed** and is the accepted way to\n  acknowledge AI assistance transparently. Human\n  coauthors should usually also have their own Signed-off-by.\n\n## C code conventions\n\n- **Indentation is 4 spaces per level.** Existing files use tabs with\n  `ts=8 sts=4 sw=4 noet` (set by the modeline in the file),\n  so tabs of width 8 appear where two levels of indent collapse. `sign.c`,\n  `sound.c`, and any new file must use spaces only and follow the style from\n  the .editorconfig file.\n- **Opening braces go on their own line (Allman style)** — for function\n  definitions and for control-flow constructs (`if`/`else`/`for`/`while`/\n  `do`) alike.\n- **Function definitions**: return type on its own indented line, with\n  the function name beginning on the next line.\n- Initialize locals where a reader cannot trivially see the first\n  assignment (common for pointers and return-value accumulators).\n  Don't add `= 0` initializers for values that are always assigned\n  before use — they can hide real uninitialized-read bugs from\n  the compiler.\n- `for (int i = 0; ...)` loop declarations are fine in files that\n  use them; older files may declare the counter at the top of the\n  block.\n- **Function-scope declarations at the top of a block** is the historical\n  style, but mid-block declarations are acceptable in files that have\n  adopted them. Match the surrounding code.\n- **Custom types end in `_T`** (e.g., `buf_T`, `linenr_T`, `pos_T`).\n  Never use `_t` — it collides with POSIX typedefs.\n- **C language is C95 plus specific C99 features**: `//` comments,\n  mixed declarations and statements, `__func__`, `bool`/`_Bool`,\n  variadic macros, compound literals, `static inline`, trailing enum\n  commas. Do not reach for later C standards — Vim still must build\n  with Compaq C on OpenVMS. See `*assumptions-C-compiler*` in\n  `develop.txt` for the full list.\n- **`bool` / `true` / `false` are acceptable.** Vim is transitioning\n  from `int` with `TRUE`/`FALSE` to C99 `bool`. Do not \"fix\" `bool`\n  back to `int`. Within a single patch, be consistent — don't mix\n  `true` and `TRUE` in new code.\n- **Do not mass-convert** `TRUE`/`FALSE` to `true`/`false` across files\n  unless that is the patch's explicit purpose. Opportunistic\n  conversions create noise in diffs.\n- **`STRLEN_LITERAL(\"...\")`** should be used when the length of a\n  string literal is needed. Avoid `STRLEN()` on literals.\n- **`vim_snprintf_safelen()`** returns the written length; prefer it\n  over `vim_snprintf()` when the length is then needed.\n- **Prefer `dict_add_string_len()`** when the string length is already\n  known, over `dict_add_string()` which calls `STRLEN()`.\n- **String/buffer parameters go `(char_u *buf, size_t buflen)`** —\n  length alongside pointer, in bytes. Use `size_t` for byte counts,\n  `int` only where required by legacy APIs.\n- **Guards before divisions.** Check for divisor zero explicitly, even\n  when a composite earlier guard would prevent it. Relying on\n  transitive guards is fragile.\n- When introducing new allocations, verify the cleanup paths handle all exit\n  conditions (early return, error branches, etc).\n\n**Use Vim wrappers instead of libc where one exists:**\n\n| libc          | Vim                    | Why                         |\n|---------------|------------------------|-----------------------------|\n| `free()`      | `vim_free()`           | Tolerates NULL              |\n| `malloc()`    | `alloc()` / `lalloc()` | Checks for OOM              |\n| `strcpy()`    | `STRCPY()`             | Cast for `char_u *`         |\n| `strchr()`    | `vim_strchr()`         | Handles special characters  |\n| `strrchr()`   | `vim_strrchr()`        | Handles special characters  |\n| `memcpy()`    | `mch_memmove()`        | Handles overlapping copies  |\n| `bcopy()`     | `mch_memmove()`        | Handles overlapping copies  |\n| `memset()`    | `vim_memset()`         | Uniform across systems      |\n| `isspace()`   | `vim_isspace()`        | Handles bytes > 127         |\n| `iswhite()`   | `vim_iswhite()`        | TRUE only for tab and space |\n\nFurther rules, not spelled out here, live in `runtime/doc/develop.txt`:\n\n- `*style-names*` — reserved name patterns (`is*`, `to*`, `str*`, `mem*`,\n  `wcs*`, `.*_t`, `__.*`), forbidden identifiers (`delete`, `this`, `new`,\n  `time`, `index`), and the 31-character function-name limit.\n- `*style-spaces*`, `*style-examples*` — spacing and one-statement-per-line.\n- `*style-various*` — `FEAT_` feature prefix, uppercase `#define`,\n  `#ifdef HAVE_X` rather than `#if HAVE_X`, no `'\\\"'`.\n- `*assumptions-makefiles*` — POSIX.1-2001 `make` only in the main\n  Makefiles (no `%` rules, `:=`, `.ONESHELL`, GNU conditionals).\n- Vim uses `char_u` instead of `char` type\n- Vim uses the macros `STRLEN`, `STRCPY`, `STRCMP`, `STRCAT` that work\n  with the `char_u` type.\n- `*style-clang-format*` — `sign.c` and `sound.c` are formatted with\n  `clang-format`; re-run it after editing those files.\n\n## Vim9 script conventions (in tests and runtime files)\n\n- Write modern Vim style (new files can use Vim9 script, but compatibility\n  with Neovim and other forks is a concern, so in doubt please ask!)\n- **Drop `l:` prefix from local variables** in Vim-script tests.\n- **Don't add `CheckFeature` inside individual tests** if it's already\n  at the top of the file.\n- If a test file doesn't gate features at the top, add CheckFeature to\n  individual tests that depend on specific build features.\n\n## Test conventions\n\n- Tests are in `src/testdir/test_*.vim`.\n- Reproducible tests beat \"it doesn't crash\" tests. If a patch fixes\n  a rendering bug, add a screendump test. If it fixes incorrect output,\n  assert the output.\n- Add comprehensive tests for newly added features and include them\n  in existing tests if possible\n- **Screendump tests** use `CheckScreendump`, `RunVimInTerminal`,\n  `VerifyScreenDump`, and live dumps in `src/testdir/dumps/`.\n- `v9.CheckScriptSuccess(lines)` / `v9.CheckScriptFailure(lines, error, lnum)`\n  are the standard way to test Vim9 script behavior at script-load time.\n- When fixing a bug reported as an issue, include a test that\n  reproduces the original report, not just a minimal synthetic case.\n- Tests for Syntax runtime are in `runtime/syntax/testdir`\n- Tests for Indent runtime are in `runtime/indent/testdir`\n\n## Common gotchas\n\n- **Distinguish what code enforces from what docs claim.** If a patch\n  changes documented behavior, say so in the Problem/Solution.\n- **Generated files** (`src/auto/configure`, generated Wayland protocol\n  C, etc.) should only be regenerated when their source changes.\n  Mixing unrelated regeneration into a functional patch creates noise.\n\n## Documentation\n\n- User-facing option or feature changes require a `runtime/doc/*.txt`\n  update in the same patch.\n- When editing an existing help file, bump the `Last change:` header\n  at the top.\n\n### Help file style\n\nSee `runtime/doc/helphelp.txt` (`*help-writing*`) for the authoritative\nreference. Key conventions:\n\n- **File header**: first line is `*filename.txt*` then a tab then a\n  short description. That description appears under `LOCAL ADDITIONS`\n  in `help.txt`. The version and `Last change:` date go on the second\n  line, right aligned.\n- **Modeline**: every help file ends with a Vim modeline — typically\n  `vim:tw=78:ts=8:noet:ft=help:norl:`.\n- **Layout**: `'textwidth'` 78, `'tabstop'` 8, indent and align with\n  tab characters. Two spaces between sentences. Run `:retab`\n  (not `:retab!`, and review the diff) after editing.\n- **Tags** are defined as `*tag-name*`, usually right-aligned on the\n  line where the thing they name is introduced. Tag names must be\n  unique across all of `runtime/doc/`; for plugin help, prefix with\n  the plugin name.\n- **Cross-references inside help text**:\n    - `|tag-name|` — hot-link to an existing tag.\n    - `` `:cmd` `` — Ex command, highlighted as a code block.\n    - `'option'` — option name, in single quotes.\n    - `<Key>` or `CTRL-X` — special keys.\n    - `{placeholder}` — user-supplied argument.\n- **Sections** are separated by a line of `=` starting in column 1.\n  Column or subsection headings end with `~` to trigger heading\n  highlighting.\n- **Code blocks** start with `>` at the end of the introducing line\n  and end with `<` as the first non-blank on a later line (any line\n  starting in column 1 also implicitly closes the block). Use `>vim`\n  (or another language name) to request syntax highlighting inside\n  the block.\n- **Notation** — `Note`, `Todo`, `Error` and a few similar words are\n  auto-highlighted; do not try to fake the highlighting by other means.\n- **Language**: gender-neutral language is preferred for new or updated\n  text; existing wording does not need to be rewritten for this alone.\n\n## Release policy\n\nVim alternates between development cycles and stability periods — see\n`runtime/doc/develop.txt` `*design-policy*`.\n\n- **During a stability period** only clear bug fixes, security fixes,\n  documentation updates, translations, and runtime file updates are\n  accepted. No new features, no backwards-incompatible changes.\n- **Once released in a minor version**, C-core features must stay\n  backwards-compatible. Runtime files have a bit more flexibility so\n  their maintainers can correct old behavior.\n- **Deprecated features** stay reachable via config (do not hard-error),\n  are documented as deprecated, can be disabled at compile time, and\n  may be removed in a later cycle.\n\n## Security\n\nBefore reporting a suspected security issue or submitting a patch\nthat touches security-sensitive code, read `SECURITY.md`. Follow\nthe disclosure process described there.\n\n## Before submitting\n\n1. Commit message follows the format above.\n2. All modified code compiles without new warnings.\n3. Tests pass, and new functionality has regression tests.\n4. Documentation is updated for user-visible changes.\n5. Signed-off-by is present.\n6. Diff contains only changes relevant to the stated problem —\n   no stray whitespace fixes, no unrelated refactors, no unrelated\n   regeneration of `auto/configure`.\n7. For multi-patch series: each commit compiles and passes its own\n   tests. A known-broken intermediate state that a later patch fixes\n   is not acceptable — squash instead.\n\n## When in doubt\n\n- Make the smallest possible change to achieve the goal. Do not rewrite\n  entire files or functions when a targeted edit suffices.\n- Read surrounding code and match its style rather than imposing an\n  \"improvement.\"\n- Err toward smaller, more focused patches. A patch that does three\n  things is three patches.\n- If a patch fixes a symptom of a deeper bug, say so in the Problem\n  and acknowledge the scope limitation in the Solution.\n- Before claiming a bug exists, reproduce it. Before claiming code does X, read\n  the code. Do not rely on training-data memory of file contents.\n- Before running shell commands that modify files outside the working tree,\n  install packages, push branches, or invoke network operations, confirm with\n  the user.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nGuidance for AI coding agents working in the Vim repository.\n\n## Project\n\nVim is a text editor written in C. The canonical repository is\nhttps://github.com/vim/vim. The code is old and has grown organically over\nthe past 30+ years. Some files are vendored from upstream projects\n(`src/xdiff`, `src/libvterm`); parts of the runtime are occasionally shared\nwith forks like Neovim.\n\nVim strives to be portable across several different operating systems and\naims to be a stable, robust editor gradually developing new features while\nremaining backwards compatible as much as possible.\n\nAt the same time, Vim can be compiled with different feature sets, from the\nPOSIX compatible minimal vi to a full-fledged GUI editor which includes\nadditional scripting interfaces.\n\nSee `runtime/doc/develop.txt` for the high level design goals.\n\n## Build and test\n\n    # Full build on Unix/Linux (from src/):\n    make\n\n    # Run the full test suite:\n    make test\n\n    # Generate proto files\n    make proto\n\n    # Run a single test file:\n    cd src/testdir && make test_name.res\n\nOutput is in testdir/messages and testdir/test.log\n\nBuilds on Windows depend on the Environment, see `src/INSTALLpc.txt`\nfor Cygwin/MSYS and MSVC ways to build Vim\n\nBefore submitting any patch, at minimum:\n1. The build succeeds without new warnings.\n2. Relevant tests pass.\n3. The code matches the style of the file being edited.\n\n## Layout\n\n- `src/` - the C source. Subsystem names are usually obvious from filenames\n  (`buffer.c`, `window.c`, `search.c`, `vim9compile.c`, etc.).\n- `src/proto/` - function prototypes, one `.pro` file per source file.\n  Regenerated; do not hand-edit unless you know what you're doing.\n- `src/po` - Translations\n- `src/xxd` - for the xxd subproject\n- `src/xdiff` - for the xdiff library (imported from git)\n- `src/libvterm` - for the libvterm library\n- `src/testdir/` - tests. Vim-script files named `test_*.vim`.\n  Screendump expected output lives in `src/testdir/dumps/`.\n- `runtime/doc/` - user-facing documentation in Vim help format, when updating,\n  also update the Last Change header\n- `runtime/syntax/generator` - Syntax script for Vim Script, automatically generated\n  from Vims source\n- `runtime/`  - runtime files shipped with Vim, when updating, also update the\n  Last Change header and a short description if this file has no maintainer\n  If the file has a maintainer, changes should go via them (so make a merge\n  request against the upstream repo instead)\n- `src/version.c` - contains the `included_patches[]` list. Every\n  patch touching anything below `src/` (with the exception of `src/po`) needs a\n  new entry at the top, will be updated only when merging into\n  the master tree.\n\n## Commit format\n\nVim uses a strict commit message format. The subject line is a\none-sentence **problem statement**, not a description of the fix:\n\n    patch 9.2.NNNN: short description of the problem\n\n    Problem:  Restatement of the problem as a full sentence, possibly\n              with a reporter attribution in parentheses.\n    Solution: Short description of the fix, ending with the author's\n              name in parentheses.\n\n    optional longer description of the problem and solution goes here in prose.\n    Do not use bullet points.\n\n    fixes:   #NNNN\n    related: #NNNN\n    closes:  #NNNN\n\n    Co-authored-by: Name\n    Signed-off-by: Author Name <email>\n\nRules:\n\n- **Subject line states the problem**, not the solution. \"fix typo\" is\n  wrong; \"typo in foo() causes OOB read\" is right.\n- **Problem line is a full sentence with a trailing period.** It mirrors\n  the subject.\n- **Solution line ends with `(Author Name)`** — parentheses, period\n  after them.\n- **Longer prose**, if any, goes after the Problem/Solution header\n- **`fixes:` references the issue** the patch fixes.\n  **`closes:` references the PR** that introduces the fix.\n  **`related:` references related issues**, including issues that caused this\n  one.\n  All can appear. Colon, aligned, no trailing period.\n- **`Signed-off-by:` is required** — DCO.\n- **`Co-Authored-By:` is allowed** and is the accepted way to\n  acknowledge AI assistance transparently. Human\n  coauthors should usually also have their own Signed-off-by.\n\n## C code conventions\n\n- **Indentation is 4 spaces per level.** Existing files use tabs with\n  `ts=8 sts=4 sw=4 noet` (set by the modeline in the file),\n  so tabs of width 8 appear where two levels of indent collapse. `sign.c`,\n  `sound.c`, and any new file must use spaces only and follow the style from\n  the .editorconfig file.\n- **Opening braces go on their own line (Allman style)** — for function\n  definitions and for control-flow constructs (`if`/`else`/`for`/`while`/\n  `do`) alike.\n- **Function definitions**: return type on its own indented line, with\n  the function name beginning on the next line.\n- Initialize locals where a reader cannot trivially see the first\n  assignment (common for pointers and return-value accumulators).\n  Don't add `= 0` initializers for values that are always assigned\n  before use — they can hide real uninitialized-read bugs from\n  the compiler.\n- `for (int i = 0; ...)` loop declarations are fine in files that\n  use them; older files may declare the counter at the top of the\n  block.\n- **Function-scope declarations at the top of a block** is the historical\n  style, but mid-block declarations are acceptable in files that have\n  adopted them. Match the surrounding code.\n- **Custom types end in `_T`** (e.g., `buf_T`, `linenr_T`, `pos_T`).\n  Never use `_t` — it collides with POSIX typedefs.\n- **C language is C95 plus specific C99 features**: `//` comments,\n  mixed declarations and statements, `__func__`, `bool`/`_Bool`,\n  variadic macros, compound literals, `static inline`, trailing enum\n  commas. Do not reach for later C standards — Vim still must build\n  with Compaq C on OpenVMS. See `*assumptions-C-compiler*` in\n  `develop.txt` for the full list.\n- **`bool` / `true` / `false` are acceptable.** Vim is transitioning\n  from `int` with `TRUE`/`FALSE` to C99 `bool`. Do not \"fix\" `bool`\n  back to `int`. Within a single patch, be consistent — don't mix\n  `true` and `TRUE` in new code.\n- **Do not mass-convert** `TRUE`/`FALSE` to `true`/`false` across files\n  unless that is the patch's explicit purpose. Opportunistic\n  conversions create noise in diffs.\n- **`STRLEN_LITERAL(\"...\")`** should be used when the length of a\n  string literal is needed. Avoid `STRLEN()` on literals.\n- **`vim_snprintf_safelen()`** returns the written length; prefer it\n  over `vim_snprintf()` when the length is then needed.\n- **Prefer `dict_add_string_len()`** when the string length is already\n  known, over `dict_add_string()` which calls `STRLEN()`.\n- **String/buffer parameters go `(char_u *buf, size_t buflen)`** —\n  length alongside pointer, in bytes. Use `size_t` for byte counts,\n  `int` only where required by legacy APIs.\n- **Guards before divisions.** Check for divisor zero explicitly, even\n  when a composite earlier guard would prevent it. Relying on\n  transitive guards is fragile.\n- When introducing new allocations, verify the cleanup paths handle all exit\n  conditions (early return, error branches, etc).\n\n**Use Vim wrappers instead of libc where one exists:**\n\n| libc          | Vim                    | Why                         |\n|---------------|------------------------|-----------------------------|\n| `free()`      | `vim_free()`           | Tolerates NULL              |\n| `malloc()`    | `alloc()` / `lalloc()` | Checks for OOM              |\n| `strcpy()`    | `STRCPY()`             | Cast for `char_u *`         |\n| `strchr()`    | `vim_strchr()`         | Handles special characters  |\n| `strrchr()`   | `vim_strrchr()`        | Handles special characters  |\n| `memcpy()`    | `mch_memmove()`        | Handles overlapping copies  |\n| `bcopy()`     | `mch_memmove()`        | Handles overlapping copies  |\n| `memset()`    | `vim_memset()`         | Uniform across systems      |\n| `isspace()`   | `vim_isspace()`        | Handles bytes > 127         |\n| `iswhite()`   | `vim_iswhite()`        | TRUE only for tab and space |\n\nFurther rules, not spelled out here, live in `runtime/doc/develop.txt`:\n\n- `*style-names*` — reserved name patterns (`is*`, `to*`, `str*`, `mem*`,\n  `wcs*`, `.*_t`, `__.*`), forbidden identifiers (`delete`, `this`, `new`,\n  `time`, `index`), and the 31-character function-name limit.\n- `*style-spaces*`, `*style-examples*` — spacing and one-statement-per-line.\n- `*style-various*` — `FEAT_` feature prefix, uppercase `#define`,\n  `#ifdef HAVE_X` rather than `#if HAVE_X`, no `'\\\"'`.\n- `*assumptions-makefiles*` — POSIX.1-2001 `make` only in the main\n  Makefiles (no `%` rules, `:=`, `.ONESHELL`, GNU conditionals).\n- Vim uses `char_u` instead of `char` type\n- Vim uses the macros `STRLEN`, `STRCPY`, `STRCMP`, `STRCAT` that work\n  with the `char_u` type.\n- `*style-clang-format*` — `sign.c` and `sound.c` are formatted with\n  `clang-format`; re-run it after editing those files.\n\n## Vim9 script conventions (in tests and runtime files)\n\n- Write modern Vim style (new files can use Vim9 script, but compatibility\n  with Neovim and other forks is a concern, so in doubt please ask!)\n- **Drop `l:` prefix from local variables** in Vim-script tests.\n- **Don't add `CheckFeature` inside individual tests** if it's already\n  at the top of the file.\n- If a test file doesn't gate features at the top, add CheckFeature to\n  individual tests that depend on specific build features.\n\n## Test conventions\n\n- Tests are in `src/testdir/test_*.vim`.\n- Reproducible tests beat \"it doesn't crash\" tests. If a patch fixes\n  a rendering bug, add a screendump test. If it fixes incorrect output,\n  assert the output.\n- Add comprehensive tests for newly added features and include them\n  in existing tests if possible\n- **Screendump tests** use `CheckScreendump`, `RunVimInTerminal`,\n  `VerifyScreenDump`, and live dumps in `src/testdir/dumps/`.\n- `v9.CheckScriptSuccess(lines)` / `v9.CheckScriptFailure(lines, error, lnum)`\n  are the standard way to test Vim9 script behavior at script-load time.\n- When fixing a bug reported as an issue, include a test that\n  reproduces the original report, not just a minimal synthetic case.\n- Tests for Syntax runtime are in `runtime/syntax/testdir`\n- Tests for Indent runtime are in `runtime/indent/testdir`\n\n## Common gotchas\n\n- **Distinguish what code enforces from what docs claim.** If a patch\n  changes documented behavior, say so in the Problem/Solution.\n- **Generated files** (`src/auto/configure`, generated Wayland protocol\n  C, etc.) should only be regenerated when their source changes.\n  Mixing unrelated regeneration into a functional patch creates noise.\n\n## Documentation\n\n- User-facing option or feature changes require a `runtime/doc/*.txt`\n  update in the same patch.\n- When editing an existing help file, bump the `Last change:` header\n  at the top.\n\n### Help file style\n\nSee `runtime/doc/helphelp.txt` (`*help-writing*`) for the authoritative\nreference. Key conventions:\n\n- **File header**: first line is `*filename.txt*` then a tab then a\n  short description. That description appears under `LOCAL ADDITIONS`\n  in `help.txt`. The version and `Last change:` date go on the second\n  line, right aligned.\n- **Modeline**: every help file ends with a Vim modeline — typically\n  `vim:tw=78:ts=8:noet:ft=help:norl:`.\n- **Layout**: `'textwidth'` 78, `'tabstop'` 8, indent and align with\n  tab characters. Two spaces between sentences. Run `:retab`\n  (not `:retab!`, and review the diff) after editing.\n- **Tags** are defined as `*tag-name*`, usually right-aligned on the\n  line where the thing they name is introduced. Tag names must be\n  unique across all of `runtime/doc/`; for plugin help, prefix with\n  the plugin name.\n- **Cross-references inside help text**:\n    - `|tag-name|` — hot-link to an existing tag.\n    - `` `:cmd` `` — Ex command, highlighted as a code block.\n    - `'option'` — option name, in single quotes.\n    - `<Key>` or `CTRL-X` — special keys.\n    - `{placeholder}` — user-supplied argument.\n- **Sections** are separated by a line of `=` starting in column 1.\n  Column or subsection headings end with `~` to trigger heading\n  highlighting.\n- **Code blocks** start with `>` at the end of the introducing line\n  and end with `<` as the first non-blank on a later line (any line\n  starting in column 1 also implicitly closes the block). Use `>vim`\n  (or another language name) to request syntax highlighting inside\n  the block.\n- **Notation** — `Note`, `Todo`, `Error` and a few similar words are\n  auto-highlighted; do not try to fake the highlighting by other means.\n- **Language**: gender-neutral language is preferred for new or updated\n  text; existing wording does not need to be rewritten for this alone.\n\n## Release policy\n\nVim alternates between development cycles and stability periods — see\n`runtime/doc/develop.txt` `*design-policy*`.\n\n- **During a stability period** only clear bug fixes, security fixes,\n  documentation updates, translations, and runtime file updates are\n  accepted. No new features, no backwards-incompatible changes.\n- **Once released in a minor version**, C-core features must stay\n  backwards-compatible. Runtime files have a bit more flexibility so\n  their maintainers can correct old behavior.\n- **Deprecated features** stay reachable via config (do not hard-error),\n  are documented as deprecated, can be disabled at compile time, and\n  may be removed in a later cycle.\n\n## Security\n\nBefore reporting a suspected security issue or submitting a patch\nthat touches security-sensitive code, read `SECURITY.md`. Follow\nthe disclosure process described there.\n\n## Before submitting\n\n1. Commit message follows the format above.\n2. All modified code compiles without new warnings.\n3. Tests pass, and new functionality has regression tests.\n4. Documentation is updated for user-visible changes.\n5. Signed-off-by is present.\n6. Diff contains only changes relevant to the stated problem —\n   no stray whitespace fixes, no unrelated refactors, no unrelated\n   regeneration of `auto/configure`.\n7. For multi-patch series: each commit compiles and passes its own\n   tests. A known-broken intermediate state that a later patch fixes\n   is not acceptable — squash instead.\n\n## When in doubt\n\n- Make the smallest possible change to achieve the goal. Do not rewrite\n  entire files or functions when a targeted edit suffices.\n- Read surrounding code and match its style rather than imposing an\n  \"improvement.\"\n- Err toward smaller, more focused patches. A patch that does three\n  things is three patches.\n- If a patch fixes a symptom of a deeper bug, say so in the Problem\n  and acknowledge the scope limitation in the Solution.\n- Before claiming a bug exists, reproduce it. Before claiming code does X, read\n  the code. Do not rely on training-data memory of file contents.\n- Before running shell commands that modify files outside the working tree,\n  install packages, push branches, or invoke network operations, confirm with\n  the user.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nGuidance for AI coding agents working in the Vim repository.\n\n## Project\n\nVim is a text editor written in C. The canonical repository is\nhttps://github.com/vim/vim. The code is old and has grown organically over\nthe past 30+ years. Some files are vendored from upstream projects\n(`src/xdiff`, `src/libvterm`); parts of the runtime are occasionally shared\nwith forks like Neovim.\n\nVim strives to be portable across several different operating systems and\naims to be a stable, robust editor gradually developing new features while\nremaining backwards compatible as much as possible.\n\nAt the same time, Vim can be compiled with different feature sets, from the\nPOSIX compatible minimal vi to a full-fledged GUI editor which includes\nadditional scripting interfaces.\n\nSee `runtime/doc/develop.txt` for the high level design goals.\n\n## Build and test\n\n    # Full build on Unix/Linux (from src/):\n    make\n\n    # Run the full test suite:\n    make test\n\n    # Generate proto files\n    make proto\n\n    # Run a single test file:\n    cd src/testdir && make test_name.res\n\nOutput is in testdir/messages and testdir/test.log\n\nBuilds on Windows depend on the Environment, see `src/INSTALLpc.txt`\nfor Cygwin/MSYS and MSVC ways to build Vim\n\nBefore submitting any patch, at minimum:\n1. The build succeeds without new warnings.\n2. Relevant tests pass.\n3. The code matches the style of the file being edited.\n\n## Layout\n\n- `src/` - the C source. Subsystem names are usually obvious from filenames\n  (`buffer.c`, `window.c`, `search.c`, `vim9compile.c`, etc.).\n- `src/proto/` - function prototypes, one `.pro` file per source file.\n  Regenerated; do not hand-edit unless you know what you're doing.\n- `src/po` - Translations\n- `src/xxd` - for the xxd subproject\n- `src/xdiff` - for the xdiff library (imported from git)\n- `src/libvterm` - for the libvterm library\n- `src/testdir/` - tests. Vim-script files named `test_*.vim`.\n  Screendump expected output lives in `src/testdir/dumps/`.\n- `runtime/doc/` - user-facing documentation in Vim help format, when updating,\n  also update the Last Change header\n- `runtime/syntax/generator` - Syntax script for Vim Script, automatically generated\n  from Vims source\n- `runtime/`  - runtime files shipped with Vim, when updating, also update the\n  Last Change header and a short description if this file has no maintainer\n  If the file has a maintainer, changes should go via them (so make a merge\n  request against the upstream repo instead)\n- `src/version.c` - contains the `included_patches[]` list. Every\n  patch touching anything below `src/` (with the exception of `src/po`) needs a\n  new entry at the top, will be updated only when merging into\n  the master tree.\n\n## Commit format\n\nVim uses a strict commit message format. The subject line is a\none-sentence **problem statement**, not a description of the fix:\n\n    patch 9.2.NNNN: short description of the problem\n\n    Problem:  Restatement of the problem as a full sentence, possibly\n              with a reporter attribution in parentheses.\n    Solution: Short description of the fix, ending with the author's\n              name in parentheses.\n\n    optional longer description of the problem and solution goes here in prose.\n    Do not use bullet points.\n\n    fixes:   #NNNN\n    related: #NNNN\n    closes:  #NNNN\n\n    Co-authored-by: Name\n    Signed-off-by: Author Name <email>\n\nRules:\n\n- **Subject line states the problem**, not the solution. \"fix typo\" is\n  wrong; \"typo in foo() causes OOB read\" is right.\n- **Problem line is a full sentence with a trailing period.** It mirrors\n  the subject.\n- **Solution line ends with `(Author Name)`** — parentheses, period\n  after them.\n- **Longer prose**, if any, goes after the Problem/Solution header\n- **`fixes:` references the issue** the patch fixes.\n  **`closes:` references the PR** that introduces the fix.\n  **`related:` references related issues**, including issues that caused this\n  one.\n  All can appear. Colon, aligned, no trailing period.\n- **`Signed-off-by:` is required** — DCO.\n- **`Co-Authored-By:` is allowed** and is the accepted way to\n  acknowledge AI assistance transparently. Human\n  coauthors should usually also have their own Signed-off-by.\n\n## C code conventions\n\n- **Indentation is 4 spaces per level.** Existing files use tabs with\n  `ts=8 sts=4 sw=4 noet` (set by the modeline in the file),\n  so tabs of width 8 appear where two levels of indent collapse. `sign.c`,\n  `sound.c`, and any new file must use spaces only and follow the style from\n  the .editorconfig file.\n- **Opening braces go on their own line (Allman style)** — for function\n  definitions and for control-flow constructs (`if`/`else`/`for`/`while`/\n  `do`) alike.\n- **Function definitions**: return type on its own indented line, with\n  the function name beginning on the next line.\n- Initialize locals where a reader cannot trivially see the first\n  assignment (common for pointers and return-value accumulators).\n  Don't add `= 0` initializers for values that are always assigned\n  before use — they can hide real uninitialized-read bugs from\n  the compiler.\n- `for (int i = 0; ...)` loop declarations are fine in files that\n  use them; older files may declare the counter at the top of the\n  block.\n- **Function-scope declarations at the top of a block** is the historical\n  style, but mid-block declarations are acceptable in files that have\n  adopted them. Match the surrounding code.\n- **Custom types end in `_T`** (e.g., `buf_T`, `linenr_T`, `pos_T`).\n  Never use `_t` — it collides with POSIX typedefs.\n- **C language is C95 plus specific C99 features**: `//` comments,\n  mixed declarations and statements, `__func__`, `bool`/`_Bool`,\n  variadic macros, compound literals, `static inline`, trailing enum\n  commas. Do not reach for later C standards — Vim still must build\n  with Compaq C on OpenVMS. See `*assumptions-C-compiler*` in\n  `develop.txt` for the full list.\n- **`bool` / `true` / `false` are acceptable.** Vim is transitioning\n  from `int` with `TRUE`/`FALSE` to C99 `bool`. Do not \"fix\" `bool`\n  back to `int`. Within a single patch, be consistent — don't mix\n  `true` and `TRUE` in new code.\n- **Do not mass-convert** `TRUE`/`FALSE` to `true`/`false` across files\n  unless that is the patch's explicit purpose. Opportunistic\n  conversions create noise in diffs.\n- **`STRLEN_LITERAL(\"...\")`** should be used when the length of a\n  string literal is needed. Avoid `STRLEN()` on literals.\n- **`vim_snprintf_safelen()`** returns the written length; prefer it\n  over `vim_snprintf()` when the length is then needed.\n- **Prefer `dict_add_string_len()`** when the string length is already\n  known, over `dict_add_string()` which calls `STRLEN()`.\n- **String/buffer parameters go `(char_u *buf, size_t buflen)`** —\n  length alongside pointer, in bytes. Use `size_t` for byte counts,\n  `int` only where required by legacy APIs.\n- **Guards before divisions.** Check for divisor zero explicitly, even\n  when a composite earlier guard would prevent it. Relying on\n  transitive guards is fragile.\n- When introducing new allocations, verify the cleanup paths handle all exit\n  conditions (early return, error branches, etc).\n\n**Use Vim wrappers instead of libc where one exists:**\n\n| libc          | Vim                    | Why                         |\n|---------------|------------------------|-----------------------------|\n| `free()`      | `vim_free()`           | Tolerates NULL              |\n| `malloc()`    | `alloc()` / `lalloc()` | Checks for OOM              |\n| `strcpy()`    | `STRCPY()`             | Cast for `char_u *`         |\n| `strchr()`    | `vim_strchr()`         | Handles special characters  |\n| `strrchr()`   | `vim_strrchr()`        | Handles special characters  |\n| `memcpy()`    | `mch_memmove()`        | Handles overlapping copies  |\n| `bcopy()`     | `mch_memmove()`        | Handles overlapping copies  |\n| `memset()`    | `vim_memset()`         | Uniform across systems      |\n| `isspace()`   | `vim_isspace()`        | Handles bytes > 127         |\n| `iswhite()`   | `vim_iswhite()`        | TRUE only for tab and space |\n\nFurther rules, not spelled out here, live in `runtime/doc/develop.txt`:\n\n- `*style-names*` — reserved name patterns (`is*`, `to*`, `str*`, `mem*`,\n  `wcs*`, `.*_t`, `__.*`), forbidden identifiers (`delete`, `this`, `new`,\n  `time`, `index`), and the 31-character function-name limit.\n- `*style-spaces*`, `*style-examples*` — spacing and one-statement-per-line.\n- `*style-various*` — `FEAT_` feature prefix, uppercase `#define`,\n  `#ifdef HAVE_X` rather than `#if HAVE_X`, no `'\\\"'`.\n- `*assumptions-makefiles*` — POSIX.1-2001 `make` only in the main\n  Makefiles (no `%` rules, `:=`, `.ONESHELL`, GNU conditionals).\n- Vim uses `char_u` instead of `char` type\n- Vim uses the macros `STRLEN`, `STRCPY`, `STRCMP`, `STRCAT` that work\n  with the `char_u` type.\n- `*style-clang-format*` — `sign.c` and `sound.c` are formatted with\n  `clang-format`; re-run it after editing those files.\n\n## Vim9 script conventions (in tests and runtime files)\n\n- Write modern Vim style (new files can use Vim9 script, but compatibility\n  with Neovim and other forks is a concern, so in doubt please ask!)\n- **Drop `l:` prefix from local variables** in Vim-script tests.\n- **Don't add `CheckFeature` inside individual tests** if it's already\n  at the top of the file.\n- If a test file doesn't gate features at the top, add CheckFeature to\n  individual tests that depend on specific build features.\n\n## Test conventions\n\n- Tests are in `src/testdir/test_*.vim`.\n- Reproducible tests beat \"it doesn't crash\" tests. If a patch fixes\n  a rendering bug, add a screendump test. If it fixes incorrect output,\n  assert the output.\n- Add comprehensive tests for newly added features and include them\n  in existing tests if possible\n- **Screendump tests** use `CheckScreendump`, `RunVimInTerminal`,\n  `VerifyScreenDump`, and live dumps in `src/testdir/dumps/`.\n- `v9.CheckScriptSuccess(lines)` / `v9.CheckScriptFailure(lines, error, lnum)`\n  are the standard way to test Vim9 script behavior at script-load time.\n- When fixing a bug reported as an issue, include a test that\n  reproduces the original report, not just a minimal synthetic case.\n- Tests for Syntax runtime are in `runtime/syntax/testdir`\n- Tests for Indent runtime are in `runtime/indent/testdir`\n\n## Common gotchas\n\n- **Distinguish what code enforces from what docs claim.** If a patch\n  changes documented behavior, say so in the Problem/Solution.\n- **Generated files** (`src/auto/configure`, generated Wayland protocol\n  C, etc.) should only be regenerated when their source changes.\n  Mixing unrelated regeneration into a functional patch creates noise.\n\n## Documentation\n\n- User-facing option or feature changes require a `runtime/doc/*.txt`\n  update in the same patch.\n- When editing an existing help file, bump the `Last change:` header\n  at the top.\n\n### Help file style\n\nSee `runtime/doc/helphelp.txt` (`*help-writing*`) for the authoritative\nreference. Key conventions:\n\n- **File header**: first line is `*filename.txt*` then a tab then a\n  short description. That description appears under `LOCAL ADDITIONS`\n  in `help.txt`. The version and `Last change:` date go on the second\n  line, right aligned.\n- **Modeline**: every help file ends with a Vim modeline — typically\n  `vim:tw=78:ts=8:noet:ft=help:norl:`.\n- **Layout**: `'textwidth'` 78, `'tabstop'` 8, indent and align with\n  tab characters. Two spaces between sentences. Run `:retab`\n  (not `:retab!`, and review the diff) after editing.\n- **Tags** are defined as `*tag-name*`, usually right-aligned on the\n  line where the thing they name is introduced. Tag names must be\n  unique across all of `runtime/doc/`; for plugin help, prefix with\n  the plugin name.\n- **Cross-references inside help text**:\n    - `|tag-name|` — hot-link to an existing tag.\n    - `` `:cmd` `` — Ex command, highlighted as a code block.\n    - `'option'` — option name, in single quotes.\n    - `<Key>` or `CTRL-X` — special keys.\n    - `{placeholder}` — user-supplied argument.\n- **Sections** are separated by a line of `=` starting in column 1.\n  Column or subsection headings end with `~` to trigger heading\n  highlighting.\n- **Code blocks** start with `>` at the end of the introducing line\n  and end with `<` as the first non-blank on a later line (any line\n  starting in column 1 also implicitly closes the block). Use `>vim`\n  (or another language name) to request syntax highlighting inside\n  the block.\n- **Notation** — `Note`, `Todo`, `Error` and a few similar words are\n  auto-highlighted; do not try to fake the highlighting by other means.\n- **Language**: gender-neutral language is preferred for new or updated\n  text; existing wording does not need to be rewritten for this alone.\n\n## Release policy\n\nVim alternates between development cycles and stability periods — see\n`runtime/doc/develop.txt` `*design-policy*`.\n\n- **During a stability period** only clear bug fixes, security fixes,\n  documentation updates, translations, and runtime file updates are\n  accepted. No new features, no backwards-incompatible changes.\n- **Once released in a minor version**, C-core features must stay\n  backwards-compatible. Runtime files have a bit more flexibility so\n  their maintainers can correct old behavior.\n- **Deprecated features** stay reachable via config (do not hard-error),\n  are documented as deprecated, can be disabled at compile time, and\n  may be removed in a later cycle.\n\n## Security\n\nBefore reporting a suspected security issue or submitting a patch\nthat touches security-sensitive code, read `SECURITY.md`. Follow\nthe disclosure process described there.\n\n## Before submitting\n\n1. Commit message follows the format above.\n2. All modified code compiles without new warnings.\n3. Tests pass, and new functionality has regression tests.\n4. Documentation is updated for user-visible changes.\n5. Signed-off-by is present.\n6. Diff contains only changes relevant to the stated problem —\n   no stray whitespace fixes, no unrelated refactors, no unrelated\n   regeneration of `auto/configure`.\n7. For multi-patch series: each commit compiles and passes its own\n   tests. A known-broken intermediate state that a later patch fixes\n   is not acceptable — squash instead.\n\n## When in doubt\n\n- Make the smallest possible change to achieve the goal. Do not rewrite\n  entire files or functions when a targeted edit suffices.\n- Read surrounding code and match its style rather than imposing an\n  \"improvement.\"\n- Err toward smaller, more focused patches. A patch that does three\n  things is three patches.\n- If a patch fixes a symptom of a deeper bug, say so in the Problem\n  and acknowledge the scope limitation in the Solution.\n- Before claiming a bug exists, reproduce it. Before claiming code does X, read\n  the code. Do not rely on training-data memory of file contents.\n- Before running shell commands that modify files outside the working tree,\n  install packages, push branches, or invoke network operations, confirm with\n  the user.\n","category":"root","tokens":3756}]}