vim/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.