Neovim for Beginners — Session

Session management using Lua.

6 min readApr 12, 2022


Neovim for Beginners — Session

Managing sessions in Neovim is simple. By default, Neovim already provides several commands that we can use to manage sessions. In this article, we are going to

  • Understand the basic concepts and commands to manage sessions.
  • Develop a Lua module (around 100 lines of code) to help us save, list, delete and track sessions.

This article is part of the Neovim for Beginners series.

The Neovim configuration files can be found in this repository.

The Basics


The :mksession[!] <file>(:h :mks) command is used to write a Vim script that restores the current editing.

  • When ! is included an existing file is overwritten.
  • When <file> is omitted Session.vim is used.

The output of :mksession is like the :mkvimrc command. The :mkvimrc (:h :mkvimrc) command writes :map and :set commands to a file, in such a way that when these commands are executed, the current key mappings and options will be set to the same values.

For :mksession, additional commands are added to the file. Which ones depend on the sessionoptions option. The resulting file can be executed with the :source command.

A sample session file is shown below.


Session Options

The sessionoptions option changes the effect of the :mksession command. It is a comma-separated list of words. Each word enables saving and restoring something.

From the help documentation, below are the available options.

  • blank — empty windows
  • buffers — hidden and unloaded buffers, not just those in windows
  • curdir — the current directory
  • folds — manually created folds, opened/closed folds, and local fold options
  • globals — global variables that start with an uppercase letter and contain at least one lowercase…




Software engineer, Data Science and ML practitioner.