Sometimes you have to restart Vim. Usually this means losing your list of open buffers, as well as any open tab pages or windows. Fortunately, Vim’s session management allows you to save your current workspace so that you can restore it again later.

Saving and Loading Sessions Manually

The source code that accompanies this book includes a webapp directory. Switch to that directory and launch Vim, using the -O flag to open the specified files in vertical splits:

You should see the app.js and app-test.js files in adjacent windows. Now use the :mksession! command to save the session (:h :mksession):

Vim records the current session in a Session.vim file in the current working directory. You can restore your workspace to its current state by sourcing this file. Let’s try it out. Use :qa to quit Vim. Then restart Vim using the -S flag to load your session:

Everything should look just as it did when you recorded your session: you should see the same buffers arranged in the same windows.

The -S flag lets you load a session as you launch Vim. Alternatively, you can load a session while Vim is running using the :source command (:help :source). To try this out, use :qa! to quit Vim, then restart Vim without any arguments:

Next, use :source to load the session:

This produces the same result as launching Vim with the -S flag.

By default, the :mksession! command records a Session.vim file in the current working directory. Also by default, vim -S will look in the current directory for a Session.vim file to source. In both of these cases, you can provide an argument to specify the name of a session file. For example, you could use :mksession! mysession.vim to save a session, and then launch Vim with -S mysession.vim to restore that session. This way, you could record two or more different sessions for the same project.

Saving Sessions Automatically

If you like the idea of having your session recorded automatically, you should try installing the Obsession plugin^[52] by Tim Pope. You can install it to your bundle package like this:

Let’s try this out. Start by opening two files, using horizontal splits this time (just to mix things up):

Now, start tracking your session by running:

This sets up an autocommand so that the :mksession! command is triggered whenever the VimLeavePre or BufEnter events fire (see Tip 26, ​Using Autocommands to Respond to Events​). Test this out by opening the package.json file in a new tab page, then quiting Vim:

It doesn’t matter whether you exit Vim using :q, :qall, ZZ, or whatever, your session should automatically be saved. Now if you restart Vim and load the session, it should pick up from where you left off:

Not only does the new session restore buffers, windows, tabs, and so on, it also restores the autocommands that were registered when you ran the :Obsession command. So any changes made to this session will also be recorded when you quit Vim.

You can pause session tracking with the :Obsession command. This works as a toggle, so you can run the same command again to resume tracking later on. If you want to stop tracking your session altogether, run:

This removes the Session.vim file and disables the autocommands.

What Does a Session Record?

The ‘sessionoptions’ option specifies what will be recorded when you save a session (:help ’sessionoptions’). By default, the buffer list is recorded, including buffers that are not currently visible in a window. Buffer names are preserved, but buffer numbers are not. Windows are re-created, preserving the layout and sizing of any splits. Tab pages are restored in the same order, with their windows intact. Your active window and cursor position are also recorded.

Vim 8 has another mechanism for preserving state by means of a viminfo file (:h viminfo-file). In Neovim, this is called the shada file, which is short for shared data (:h shada-file). This is where your command-line history, your search history, the contents of registers, and locations of marks are recorded. The feature is enabled by default, so these aspects of state should persist between editing sessions whether or not you load a session file.

When you restart Vim, you typically lose your undo history. Neither sessions nor viminfo will help you here, but Vim’s persistent undo feature handles this. Read the next tip to learn more.