develop.txt For Vim version 9.1. Last change: 2025 Dec 13 VIM REFERENCE MANUAL by Bram Moolenaar Development of Vim. development This text is important for those who want to be involved in further developing Vim. 1. Design goals design-goals 2. Design decisions design-decisions 3. Assumptions design-assumptions 4. Coding style coding-style 5. Policy design-policy See the file README.txt in the "src" directory for an overview of the source code. Vim is open source software. Everybody is encouraged to contribute to help improving Vim. For sending patches a unified diff "diff -u" is preferred. You can create a pull request on github, but it's not required. Also see http://vim.wikia.com/wiki/How_to_make_and_submit_a_patch. ============================================================================== 1. Design goals design-goals Most important things come first (roughly). Note that quite a few items are contradicting. This is intentional. A balance must be found between them. VIM IS... VI COMPATIBLE design-compatible First of all, it should be possible to use Vim as a drop-in replacement for Vi. When the user wants to, Vim can be used in compatible mode and hardly any differences with the original Vi will be noticed. Exceptions: - We don't reproduce obvious Vi bugs in Vim. - There are different versions of Vi. I am using Version 3.7 (6/7/85) as a reference. But support for other versions is also included when possible. The Vi part of POSIX is not considered a definitive source. - Vim adds new commands, you cannot rely on some command to fail because it didn't exist in Vi. - Vim will have a lot of features that Vi doesn't have. Going back from Vim to Vi will be a problem, this cannot be avoided. - Some things are hardly ever used (open mode, sending an e-mail when crashing, etc.). Those will only be included when someone has a good reason why it should be included and it's not too much work. - For some items it is debatable whether Vi compatibility should be maintained. There will be an option flag for these. VIM IS... IMPROVED design-improved The IMproved bits of Vim should make it a better Vi, without becoming a completely different editor. Extensions are done with a "Vi spirit". - Use the keyboard as much as feasible. The mouse requires a third hand, which we don't have. Many terminals don't have a mouse. - When the mouse is used anyway, avoid the need to switch back to the keyboard. Avoid mixing mouse and keyboard handling. - Add commands and options in a consistent way. Otherwise people will have a hard time finding and remembering them. Keep in mind that more commands and options will be added later. - A feature that people do not know about is a useless feature. Don't add obscure features, or at least add hints in documentation that they exist. - Minimize using CTRL and other modifiers, they are more difficult to type. - There are many first-time and inexperienced Vim users. Make it easy for them to start using Vim and learn more over time. - There is no limit to the features that can be added. Selecting new features is one based on (1) what users ask for, (2) how much effort it takes to implement and (3) someone actually implementing it. VIM IS... MULTI PLATFORM design-multi-platform Vim tries to help as many users on as many platforms as possible. - Support many kinds of terminals. The minimal demands are cursor positioning and clear-screen. Commands should only use key strokes that most keyboards have. Support all the keys on the keyboard for mapping. - Support many platforms. A condition is that there is someone willing to do Vim development on that platform, and it doesn't mean messing up the code. - Support many compilers and libraries. Not everybody is able or allowed to install another compiler or GUI library. - People switch from one platform to another, and from GUI to terminal version. Features should be present in all versions, or at least in as many as possible with a reasonable effort. Try to avoid that users must switch between platforms to accomplish their work efficiently. - That a feature is not possible on some platforms, or only possible on one platform, does not mean it cannot be implemented. [This intentionally contradicts the previous item, these two must be balanced.] VIM IS... WELL DOCUMENTED design-documented - A feature that isn't documented is a useless feature. A patch for a new feature must include the documentation. - Documentation should be comprehensive and understandable. Using examples is recommended. - Don't make the text unnecessarily long. Less documentation means that an item is easier to find. VIM IS... HIGH SPEED AND SMALL IN SIZE design-speed-size Using Vim must not be a big attack on system resources. Keep it small and fast. - Computers are becoming faster and bigger each year. Vim can grow too, but no faster than computers are growing. Keep Vim usable on older systems. - Many users start Vim from a shell very often. Startup time must be short. - Commands must work efficiently. The time they consume must be as small as possible. Useful commands may take longer. - Don't forget that some people use Vim over a slow connection. Minimize the communication overhead. - Items that add considerably to the size and are not used by many people should be a feature that can be disabled. - Vim is a component among other components. Don't turn it into a massive application, but have it work well together with other programs. VIM IS... MAINTAINABLE design-maintain - The source code should not become a mess. It should be reliable code. - Use the same layout in all files to make it easy to read coding-style. - Use comments in a useful way! Quoting the function name and argument names is NOT useful. Do explain what they are for. - Porting to another platform should be made easy, without having to change too much platform-independent code. - Use the object-oriented spirit: Put data and code together. Minimize the knowledge spread to other parts of the code. VIM IS... FLEXIBLE design-flexible Vim should make it easy for users to work in their preferred styles rather than coercing its users into particular patterns of work. This can be for items with a large impact (e.g., the 'compatible' option) or for details. The defaults are carefully chosen such that most users will enjoy using Vim as it is. Commands and options can be used to adjust Vim to the desire of the user and its environment. VIM IS... NOT design-not - Vim is not a shell or an Operating System. It does provide a terminal window, in which you can run a shell or debugger. E.g. to be able to do this over an ssh connection. But if you don't need a text editor with that it is out of scope (use something like screen or tmux instead). A satirical way to say this: "Unlike Emacs, Vim does not attempt to include everything but the kitchen sink, but some people say that you can clean one with it. ;-)" To use Vim with gdb see terminal-debugger