The meaning of new and split

Most commands with a new token in their name should be thought of as a “new window” command, not a “new buffer” command, even though they often create new buffers as well. An important exception is enew, discussed shortly. vnew variants are just like new variants, but split vertically, whereas new variants split horizontally by default.

split commands should be thought of in the same way as new commands, since they also create new windows. Some differences exist between split and new commands. However, split variants are like new variants in that they open a new window and also, in their {file} forms, a buffer. They differ from new variants when used without the {file} argument, since then they open a new window on the current buffer rather than on a new buffer. In that case, if new were in the name of a split command (splitnew?), it could only mean “new window”, since the buffer displayed in it is decidedly not new. However, new would then be redundant with split , which already also means “new window”, regardless of buffer.

The meaning of edit

Commands with an edit token in their name are best thought of in contrast to new commands, because they do the same things as new commands, but in the current window rather than in a new window.

enew: Where new and edit meet

The enew command has both edit and new in its name, so which is it? It is more edit than new, because it does not create a new window. Therefore, it is best to think of enew as meaning “edit new buffer”. And since edit is in its name, it does so in the current window rather than a new one.

More precisely, enew means “edit new unnamed buffer in the current window” and it does not create a new window. The buffer previously displayed in the current window becomes the alternate. Since the new buffer is unnamed, it is never read from disk. The command has no {file} form, because edit {file} has the meaning you might expect from an enew {file} command. See the next section for why this is so. That is, edit {file} edits an existing {file} buffer, or else creates a new one. If new, and {file} exists on disk, then edit also reads that file into the new buffer.

In contrast to edit {file}, which creates a new named buffer as needed, enew creates a new unnamed buffer. And in contrast to edit, which edits an existing buffer, the one in the current window and reloaded from disk, editnew edits a new buffer. With edit {file} as an example, observe that a command exists that creates a new buffer, not read from disk, such that that command does not have a new token in its name.

The meaning of {file}

The interpretation of new in enew as “new buffer” is the exception, not the rule, and is why vim provides no enew {file}, instead opting for edit {file}. That is because commands with a {file} argument behave similarly with respect to buffer handling, regardless of the presence or absence of a new token in the command name. First, the command uses an existing {file} buffer if it exists. Such an existing buffer does not need to exist on disk. If no existing {file} buffer is found, it creates a new {file} buffer, empty or read from disk when applicable. You can expect this behavior from most, if not all, commands that create buffers that have a {file} form. When differences in behavior do exist, they first build on this foundation. For example, file {file} behaves almost this way, except it never reads into the {file} buffer from disk, even if {file} exists on disk.

The great debate: new window or new buffer?

Does new mean “new window” or “new buffer”? After all, there are cases when a new command creates a new window but not a new buffer, and other cases when it creates a new buffer but not a new window.

It is important to note that a window without a buffer is not a thing: a window cannot exist without a buffer, but a buffer can exist without a window. Also, when we speak of a “new buffer”, we need not mean a new unnamed buffer, nor even a new file. For instance, if a buffer named {file} does not already exist, then new {file} opens a new, named, buffer called {file}, in a new window, even if {file} exists on disk. Then, if {file} does exist on disk, new {file} reads that file into the buffer. On the other hand, if {file} does not exist on disk, then new {file} does not create the file, even though it still creates the new {file} buffer. In that case, a file is not created until the new {file} buffer is written.

The new commands are “new window” commands, not “new buffer” commands, although they also create new buffers in some cases. Consider the new {file} command. When a buffer named {file} already exists, new {file} can only mean “new window” on the existing buffer, since it does not create a new buffer at all, merely opens a new window on that buffer. Also, as noted earlier, new (buffer) would be redundant with the {file} argument for most commands, since their common behavior is to create a new buffer anyway when conditions are met. Refer to the official documentation at :h windows. The new commands are described there as “new window” commands.

Case Study: Windows and Buffers

Commands with the new token can create (a) a new window, (b) a new buffer, or (c) both. These cases include (d) a new window but not a new buffer, a real possibility in some cases, and in others, (e) a new buffer but not a new window. (enew is the only command with a new token in its name that does not create a new window, but only a new buffer.) As noted previously, with enew as the exception, it is best to think of the new commands as referring to “new window” rather than “new buffer”, even though such commands can also create new buffers. Also, new commands are not the only commands that create new windows or new buffers. There are commands that don’t mention new , yet create (f) a new window, or (g) a new buffer, (or both). It is even possible to create a new buffer named {file} that is not read from disk, even though a file named {file} also exists in the current directory. This can be accomplished using the file {file} command.)

In the examples that follow, the distinction is made between new buffers versus existing buffers; new buffers read from disk versus new buffers not read from disk; named buffers versus unnamed buffers; and buffers versus files. Also, the state of vim when a command is executed can affect the result, and this is highlighted as well.

Examples

  • a) New window, new token present
    • Command: new [{file}]
      • New Window: Yes
      • New Buffer: Any
      • Named buffer: Any
      • Read from disk: Any
      • Exists on disk: Any
      • State when executed: Any
  • b) New buffer, new token present
    • Same as previous, except
      • State when executed: {file} buffer does not exist. {file} may or may not exist on disk. If it does, the command reads the file into the new buffer.
  • c) New window and new buffer, new token present
    • Same as either of the previous
  • d) New window, but no new buffer (from disk or otherwise), new token present
    • Command: new {file}
      • New Window: Yes
      • New Buffer: No
      • Named buffer: Yes
      • Read from disk: Any
      • Exists on disk: Any
      • State when executed: {file} buffer already exists (check buffers list with :buffers). This existing buffer is shown in the new window. This existing buffer may or may not exist on disk.
  • e) New buffer but not a new window, new token present
    • Command: enew
      • New Window: No
      • New Buffer: Yes
      • Named buffer: No
      • Read from disk: No
      • Exists on disk: No
      • State when executed: Any
  • f) New window, new token not present
    • command: split [{file}] variants
      • New Window: Yes
      • New Buffer: Any
      • Named buffer: Any
      • Read from disk: Any
      • Exists on disk: Any
      • State when executed: Any
  • g) New buffer (from disk or not), new token not present
    • Command: e {file}
      • New Window: No
      • New Buffer: Any
      • Named buffer: Yes
      • Read from disk: Any
      • Exists on disk: Any
      • State when executed: Any. {file} is shown in current window, never in a new window. If {file} buffer already exists, it is shown and a new buffer is not created. Otherwise, a new buffer is created. If {file} exists on disk, it is read into the new buffer. Otherwise, the new buffer only exists in memory until written.
    • Command: file {file}
      • New Window: No
      • New Buffer: Yes
      • Named buffer: Yes
      • Read from disk: No. {file} is never read from disk, but from the buffer previously in the current window. (That buffer becomes the alternate.) If a file named {file} also exists on disk, the buffer overwrites the file when written.
      • Exists on disk: Any
      • State when executed: Any.

Help

See :h windows for new and split commands as well as buffer commands like buffers. See :h editing for edit, file, write, save, and quit commands. Some important definitions from the vim help docs are excerpted below.

:h windows-intro

The following excerpt from the Vim docs covers terminology relevant to this post.

Summary:

  • A buffer is the in-memory text of a file.
  • A window is a viewport on a buffer.
  • A tab page is a collection of windows.

A window is a viewport onto a buffer. You can use multiple windows on one buffer, or several windows on different buffers.

A buffer is a file loaded into memory for editing. The original file remains unchanged until you write the buffer to the file.

A buffer can be in one of three states:

  • active: The buffer is displayed in a window. If there is a file for this buffer, it has been read into the buffer. The buffer may have been modified since then and thus be different from the file.
  • hidden: The buffer is not displayed. If there is a file for this buffer, it has been read into the buffer. Otherwise it’s the same as an active buffer, you just can’t see it.
  • inactive: The buffer is not displayed and does not contain anything. Options for the buffer are remembered if the file was once loaded. It can contain marks from the viminfo file. But the buffer doesn’t contain text.

In a table:

state displayed in window loaded “:buffers” shows
active yes yes ‘a’
hidden no yes ‘h’
inactive no no ’ ‘

Summary of Window and Edit Commands

Below is my own summary of some of the commands discussed in this post.

Command Description
e[dit][!] Read current buffer from disk, usually to get more recent changes written from another source, or to abandon changes made in the current buffer (when used with !). Fails if buffer has changes and ! is not used.
e[dit] {file} Edit {file} buffer in current window, make previous buffer alternate. {file} can be an existing or new buffer. If {file} exists on disk, read it into the buffer.
enew Edit new unnamed buffer in current window
new Edit new unnamed buffer in new window. Same as :split | enew
new {file} Edit {file} buffer in new (horizontal) window. {file} can be an existing or new buffer. If new and {file} exists on disk, read it into the new buffer. Same as split {file}
vnew {file} Edit {file} buffer in new vertical window. same as vsplit {file}
file {file} From current buffer, create a new buffer named {file} in the current window, previous buffer becomes alternate.
save {file} Same as file {file} but also write buffer to disk.
write Save current buffer
write {file} Save current buffer to {file} but don’t switch buffers unless current buffer is unnamed
split Split current window in two horizontally, show current buffer in both
split {file} Same as new {file}
vsplit Same as split but vertical
vsplit {file} Like split {file} but vertical. Same as vnew {file}