vim-mirror/AGENTS.md

# AGENTS.md

Guidance for AI coding agents working in the Vim repository.

## Project

Vim is a text editor written in C. The canonical repository is
https://github.com/vim/vim. The code is old and has grown organically over
the past 30+ years. Some files are vendored from upstream projects
(`src/xdiff`, `src/libvterm`); parts of the runtime are occasionally shared
with forks like Neovim.

Vim strives to be portable across several different operating systems and
aims to be a stable, robust editor gradually developing new features while
remaining backwards compatible as much as possible.

At the same time, Vim can be compiled with different feature sets, from the
POSIX compatible minimal vi to a full-fledged GUI editor which includes
additional scripting interfaces.

See `runtime/doc/develop.txt` for the high level design goals.

## Build and test

    # Full build on Unix/Linux (from src/):
    make

    # Run the full test suite:
    make test

    # Generate proto files
    make proto

    # Run a single test file:
    cd src/testdir && make test_name.res

Output is in testdir/messages and testdir/test.log

Builds on Windows depend on the Environment, see `src/INSTALLpc.txt`
for Cygwin/MSYS and MSVC ways to build Vim

Before submitting any patch, at minimum:
1. The build succeeds without new warnings.
2. Relevant tests pass.
3. The code matches the style of the file being edited.

## Layout

- `src/` - the C source. Subsystem names are usually obvious from filenames
  (`buffer.c`, `window.c`, `search.c`, `vim9compile.c`, etc.).
- `src/proto/` - function prototypes, one `.pro` file per source file.
  Regenerated; do not hand-edit unless you know what you're doing.
- `src/po` - Translations
- `src/xxd` - for the xxd subproject
- `src/xdiff` - for the xdiff library (imported from git)
- `src/libvterm` - for the libvterm library
- `src/testdir/` - tests. Vim-script files named `test_*.vim`.
  Screendump expected output lives in `src/testdir/dumps/`.
- `runtime/doc/` - user-facing documentation in Vim help format, when updating,
  also update the Last Change header
- `runtime/syntax/generator` - Syntax script for Vim Script, automatically generated
  from Vims source
- `runtime/`  - runtime files shipped with Vim, when updating, also update the
  Last Change header and a short description if this file has no maintainer
  If the file has a maintainer, changes should go via them (so make a merge
  request against the upstream repo instead)
- `src/version.c` - contains the `included_patches[]` list. Every
  patch touching anything below `src/` (with the exception of `src/po`) needs a
  new entry at the top, will be updated only when merging into
  the master tree.

## Commit format

Vim uses a strict commit message format. The subject line is a
one-sentence **problem statement**, not a description of the fix:

    patch 9.2.NNNN: short description of the problem

    Problem:  Restatement of the problem as a full sentence, possibly
              with a reporter attribution in parentheses.
    Solution: Short description of the fix, ending with the author's
              name in parentheses.

    optional longer description of the problem and solution goes here in prose.
    Do not use bullet points.

    fixes:   #NNNN
    related: #NNNN
    closes:  #NNNN

    Co-authored-by: Name
    Signed-off-by: Author Name <email>

Rules:

- **Subject line states the problem**, not the solution. "fix typo" is
  wrong; "typo in foo() causes OOB read" is right.
- **Problem line is a full sentence with a trailing period.** It mirrors
  the subject.
- **Solution line ends with `(Author Name)`** — parentheses, period
  after them.
- **Longer prose**, if any, goes after the Problem/Solution header
- **`fixes:` references the issue** the patch fixes.
  **`closes:` references the PR** that introduces the fix.
  **`related:` references related issues**, including issues that caused this
  one.
  All can appear. Colon, aligned, no trailing period.
- **`Signed-off-by:` is required** — DCO.
- **`Co-Authored-By:` is allowed** and is the accepted way to
  acknowledge AI assistance transparently. Human
  coauthors should usually also have their own Signed-off-by.

## C code conventions

- **Indentation is 4 spaces per level.** Existing files use tabs with
  `ts=8 sts=4 sw=4 noet` (set by the modeline in the file),
  so tabs of width 8 appear where two levels of indent collapse. `sign.c`,
  `sound.c`, and any new file must use spaces only and follow the style from
  the .editorconfig file.
- **Opening braces go on their own line (Allman style)** — for function
  definitions and for control-flow constructs (`if`/`else`/`for`/`while`/
  `do`) alike.
- **Function definitions**: return type on its own indented line, with
  the function name beginning on the next line.
- Initialize locals where a reader cannot trivially see the first
  assignment (common for pointers and return-value accumulators).
  Don't add `= 0` initializers for values that are always assigned
  before use — they can hide real uninitialized-read bugs from
  the compiler.
- `for (int i = 0; ...)` loop declarations are fine in files that
  use them; older files may declare the counter at the top of the
  block.
- **Function-scope declarations at the top of a block** is the historical
  style, but mid-block declarations are acceptable in files that have
  adopted them. Match the surrounding code.
- **Custom types end in `_T`** (e.g., `buf_T`, `linenr_T`, `pos_T`).
  Never use `_t` — it collides with POSIX typedefs.
- **C language is C95 plus specific C99 features**: `//` comments,
  mixed declarations and statements, `__func__`, `bool`/`_Bool`,
  variadic macros, compound literals, `static inline`, trailing enum
  commas. Do not reach for later C standards — Vim still must build
  with Compaq C on OpenVMS. See `*assumptions-C-compiler*` in
  `develop.txt` for the full list.
- **`bool` / `true` / `false` are acceptable.** Vim is transitioning
  from `int` with `TRUE`/`FALSE` to C99 `bool`. Do not "fix" `bool`
  back to `int`. Within a single patch, be consistent — don't mix
  `true` and `TRUE` in new code.
- **Do not mass-convert** `TRUE`/`FALSE` to `true`/`false` across files
  unless that is the patch's explicit purpose. Opportunistic
  conversions create noise in diffs.
- **`STRLEN_LITERAL("...")`** should be used when the length of a
  string literal is needed. Avoid `STRLEN()` on literals.
- **`vim_snprintf_safelen()`** returns the written length; prefer it
  over `vim_snprintf()` when the length is then needed.
- **Prefer `dict_add_string_len()`** when the string length is already
  known, over `dict_add_string()` which calls `STRLEN()`.
- **String/buffer parameters go `(char_u *buf, size_t buflen)`** —
  length alongside pointer, in bytes. Use `size_t` for byte counts,
  `int` only where required by legacy APIs.
- **Guards before divisions.** Check for divisor zero explicitly, even
  when a composite earlier guard would prevent it. Relying on
  transitive guards is fragile.
- When introducing new allocations, verify the cleanup paths handle all exit
  conditions (early return, error branches, etc).

**Use Vim wrappers instead of libc where one exists:**

| libc          | Vim                    | Why                         |
|---------------|------------------------|-----------------------------|
| `free()`      | `vim_free()`           | Tolerates NULL              |
| `malloc()`    | `alloc()` / `lalloc()` | Checks for OOM              |
| `strcpy()`    | `STRCPY()`             | Cast for `char_u *`         |
| `strchr()`    | `vim_strchr()`         | Handles special characters  |
| `strrchr()`   | `vim_strrchr()`        | Handles special characters  |
| `memcpy()`    | `mch_memmove()`        | Handles overlapping copies  |
| `bcopy()`     | `mch_memmove()`        | Handles overlapping copies  |
| `memset()`    | `vim_memset()`         | Uniform across systems      |
| `isspace()`   | `vim_isspace()`        | Handles bytes > 127         |
| `iswhite()`   | `vim_iswhite()`        | TRUE only for tab and space |

Further rules, not spelled out here, live in `runtime/doc/develop.txt`:

- `*style-names*` — reserved name patterns (`is*`, `to*`, `str*`, `mem*`,
  `wcs*`, `.*_t`, `__.*`), forbidden identifiers (`delete`, `this`, `new`,
  `time`, `index`), and the 31-character function-name limit.
- `*style-spaces*`, `*style-examples*` — spacing and one-statement-per-line.
- `*style-various*` — `FEAT_` feature prefix, uppercase `#define`,
  `#ifdef HAVE_X` rather than `#if HAVE_X`, no `'\"'`.
- `*assumptions-makefiles*` — POSIX.1-2001 `make` only in the main
  Makefiles (no `%` rules, `:=`, `.ONESHELL`, GNU conditionals).
- Vim uses `char_u` instead of `char` type
- Vim uses the macros `STRLEN`, `STRCPY`, `STRCMP`, `STRCAT` that work
  with the `char_u` type.
- `*style-clang-format*` — `sign.c` and `sound.c` are formatted with
  `clang-format`; re-run it after editing those files.

## Vim9 script conventions (in tests and runtime files)

- Write modern Vim style (new files can use Vim9 script, but compatibility
  with Neovim and other forks is a concern, so in doubt please ask!)
- **Drop `l:` prefix from local variables** in Vim-script tests.
- **Don't add `CheckFeature` inside individual tests** if it's already
  at the top of the file.
- If a test file doesn't gate features at the top, add CheckFeature to
  individual tests that depend on specific build features.

## Test conventions

- Tests are in `src/testdir/test_*.vim`.
- Reproducible tests beat "it doesn't crash" tests. If a patch fixes
  a rendering bug, add a screendump test. If it fixes incorrect output,
  assert the output.
- Add comprehensive tests for newly added features and include them
  in existing tests if possible
- **Screendump tests** use `CheckScreendump`, `RunVimInTerminal`,
  `VerifyScreenDump`, and live dumps in `src/testdir/dumps/`.
- `v9.CheckScriptSuccess(lines)` / `v9.CheckScriptFailure(lines, error, lnum)`
  are the standard way to test Vim9 script behavior at script-load time.
- When fixing a bug reported as an issue, include a test that
  reproduces the original report, not just a minimal synthetic case.
- Tests for Syntax runtime are in `runtime/syntax/testdir`
- Tests for Indent runtime are in `runtime/indent/testdir`

## Common gotchas

- **Distinguish what code enforces from what docs claim.** If a patch
  changes documented behavior, say so in the Problem/Solution.
- **Generated files** (`src/auto/configure`, generated Wayland protocol
  C, etc.) should only be regenerated when their source changes.
  Mixing unrelated regeneration into a functional patch creates noise.

## Documentation

- User-facing option or feature changes require a `runtime/doc/*.txt`
  update in the same patch.
- When editing an existing help file, bump the `Last change:` header
  at the top.

### Help file style

See `runtime/doc/helphelp.txt` (`*help-writing*`) for the authoritative
reference. Key conventions:

- **File header**: first line is `*filename.txt*` then a tab then a
  short description. That description appears under `LOCAL ADDITIONS`
  in `help.txt`. The version and `Last change:` date go on the second
  line, right aligned.
- **Modeline**: every help file ends with a Vim modeline — typically
  `vim:tw=78:ts=8:noet:ft=help:norl:`.
- **Layout**: `'textwidth'` 78, `'tabstop'` 8, indent and align with
  tab characters. Two spaces between sentences. Run `:retab`
  (not `:retab!`, and review the diff) after editing.
- **Tags** are defined as `*tag-name*`, usually right-aligned on the
  line where the thing they name is introduced. Tag names must be
  unique across all of `runtime/doc/`; for plugin help, prefix with
  the plugin name.
- **Cross-references inside help text**:
    - `|tag-name|` — hot-link to an existing tag.
    - `` `:cmd` `` — Ex command, highlighted as a code block.
    - `'option'` — option name, in single quotes.
    - `<Key>` or `CTRL-X` — special keys.
    - `{placeholder}` — user-supplied argument.
- **Sections** are separated by a line of `=` starting in column 1.
  Column or subsection headings end with `~` to trigger heading
  highlighting.
- **Code blocks** start with `>` at the end of the introducing line
  and end with `<` as the first non-blank on a later line (any line
  starting in column 1 also implicitly closes the block). Use `>vim`
  (or another language name) to request syntax highlighting inside
  the block.
- **Notation** — `Note`, `Todo`, `Error` and a few similar words are
  auto-highlighted; do not try to fake the highlighting by other means.
- **Language**: gender-neutral language is preferred for new or updated
  text; existing wording does not need to be rewritten for this alone.

## Release policy

Vim alternates between development cycles and stability periods — see
`runtime/doc/develop.txt` `*design-policy*`.

- **During a stability period** only clear bug fixes, security fixes,
  documentation updates, translations, and runtime file updates are
  accepted. No new features, no backwards-incompatible changes.
- **Once released in a minor version**, C-core features must stay
  backwards-compatible. Runtime files have a bit more flexibility so
  their maintainers can correct old behavior.
- **Deprecated features** stay reachable via config (do not hard-error),
  are documented as deprecated, can be disabled at compile time, and
  may be removed in a later cycle.

## Security

Before reporting a suspected security issue or submitting a patch
that touches security-sensitive code, read `SECURITY.md`. Follow
the disclosure process described there.

## Before submitting

1. Commit message follows the format above.
2. All modified code compiles without new warnings.
3. Tests pass, and new functionality has regression tests.
4. Documentation is updated for user-visible changes.
5. Signed-off-by is present.
6. Diff contains only changes relevant to the stated problem —
   no stray whitespace fixes, no unrelated refactors, no unrelated
   regeneration of `auto/configure`.
7. For multi-patch series: each commit compiles and passes its own
   tests. A known-broken intermediate state that a later patch fixes
   is not acceptable — squash instead.

## When in doubt

- Make the smallest possible change to achieve the goal. Do not rewrite
  entire files or functions when a targeted edit suffices.
- Read surrounding code and match its style rather than imposing an
  "improvement."
- Err toward smaller, more focused patches. A patch that does three
  things is three patches.
- If a patch fixes a symptom of a deeper bug, say so in the Problem
  and acknowledge the scope limitation in the Solution.
- Before claiming a bug exists, reproduce it. Before claiming code does X, read
  the code. Do not rely on training-data memory of file contents.
- Before running shell commands that modify files outside the working tree,
  install packages, push branches, or invoke network operations, confirm with
  the user.