Vim sessions

As you are working with Vim in a particular project, you’ll probably be opening more than just one file. Each file you open will be represented by a buffer. You might display these open buffers in various arrangements of splits within different tab pages. Or you might use one of many available methods to jump around between open buffers. After a few minutes working on a feature, you have all the files you need opened up and arranged just like you want them.

And then you need to do a quick task on another project, or maybe work on some other part of the same project. Or you need to reboot or you get carried away with your shortcuts and accidentally close Vim. Now you have to find all those files that you had open before, open them and arrange them back to how you had them.

That’s where sessions come in. Vim allows you to save the state of your Vim in a special session file, and reload it back in later, restoring the state that you were in.

The main command for this is mksession or, abbreviated, mks. You add a file path onto the end of that, and that’s where it saves your session. For example:

:mks ~/vimsessions/fixing_jira_2125

So you’re working on that Jira issue and something else comes up. You save your session. Close all your buffers or even open Vim in a new project, open up the files you need there, do what you need to do and wrap it up.

Now you’re ready to get back to that Jira issue you put aside. Restart vim with the command:

vim -S ~/vimsessions/fixing_jira_2125

And things are right back where you left off.

You can even restore a session without restarting Vim. You just need to source that session file. Right from within Vim, type:

:source ~/vimsessions/fixing_jira_2125

Note that restoring a session like this will NOT close any open buffers in your current session. So you might want to do that first.

Sourcing a session doesn’t restore everything in Vim to the way it was before, but it does restore a whole lot. Generally speaking, it restores your open buffers, splits, tabs, the current working directory, folds, global variables, options, and mappings. There are other things that can be saved. Check the help pages for mksession and sessionoptions by typing:

:help mksession


:help sessionoptions

To make sessions a little easier to work with, I made a few mappings:

nnoremap <Leader>ss :mksession! ~/.config/nvim/sessions/
nnoremap <Leader>os :source ~/.config/nvim/sessions/
nnoremap <Leader>rs :!rm ~/.config/nvim/sessions/

I made a directory called sessions inside of my neovim config folder (~/.config/nvim/). If you’re using regular Vim, you’d want to put that somewhere else. Just make sure the folder you specify actually exists before trying to save sessions into it.

The first mapping is for saving a session, ss. Note that it calls mksession! with an exclamation point at the end, which will overwrite an existing session file if it exists. It gives the path to sessions folder I created, but leaves the command line open for me to enter an actual file name. If you forget to put the file name, Vim will just let you know that. If you later open some more files and want to update the session, just call the mapping again. Now you should be able hit the tab key to autocomplete the session name you saved earlier. If there are multiple sessions, you should be able to tab through them until you get to the one you want. Or type the first couple of characters and then tab.

The second mapping, os is open session. It just sets you up to source one of the session files in the sessions directory. Same deal, enter a name or use tab-complete. Hit enter and you’re back where you were.

Finally, a bonus, rs is for remove session. Same deal, it just calls !rm for the system rm command. Type the name or autocomplete. Now you can clean up your old sessions.

These are just suggestions on how to use sessions. There are plugins that do all this and more with a fancier UIs, but I think this is pretty slick for three lines of code.