Home

Awesome

sessions.nvim

a simple session manager plugin

Neovim (and Vim) support saving and loading of sessions (windows, tabs, buffers, etc), but the interface isn't the easiest to use.

sessions.nvim is a lightweight wrapper around :mksession that adds a small amount of pixie dust to make sessions management more simple and enjoyable.

sessions.nvim does not do anything automatically. Sessions will not be saved or loaded until a command or an API function is called. This is to keep the plugin simple and focused. The entire goal of sessions.nvim is to provide a wrapper around :mksession and :source, not to provide workspace management.

Other plugins exist to automatically save and load sessions for each project directory if that is what you desire. It also wouldn't be difficult to write an autocommand to load session files on nvim startup.

This readme covers most of the features of sessions.nvim, but full documentation is found in the help file :h sessions.

Note that this plugin is small in scope and complexity. It has been stable for a long time. Just because I am not making changes doesn't mean it's been abandoned! It was designed to be small and stable, and it will stay that way.

sessions.nvim requires nvim 0.7.0 as a minimum. If you have an older version of nvim, you may use the commit tagged 0.2. (4b400a37).

Example Usage

Work on a project until ready to take a break. Run :SessionsSave .session to save the current state to a hidden file .session. nvim may be closed.

Later return to the same path and open nvim. Run :SessionsLoad .session to load the saved session. Now any changes to the window layout, buffers, tabs, etc. will be saved when closing nvim.

See natecraddock/workspaces.nvim for an easy method of automatically restoring a session in saved workspace folders.

Installation

Install with your favorite Neovim package manager. Be sure to call the setup function if you wish to change the default configuration or register the user commands.

require("sessions").setup()

The setup function accepts a table to modify the default configuration:

{
    -- autocmd events which trigger a session save
    --
    -- the default is to only save session files before exiting nvim.
    -- you may wish to also save more frequently by adding "BufEnter" or any
    -- other autocmd event
    events = { "VimLeavePre" },

    -- default session filepath
    --
    -- if a path is provided here, then the path argument for commands and API
    -- functions will use session_filepath as a default if no path is provided.
    session_filepath = "",

    -- treat the default session filepath as an absolute path
    -- if true, all session files will be stored in a single directory
    absolute = false,
}

For example, the following settings will save the session every time a window is entered, and .nvim/session will be used as the default session filepath:

require("sessions").setup({
    events = { "WinEnter" },
    session_filepath = ".nvim/session",
})

When absolute is true, the session_filepath will store all session files. In the following example, all session files will be stored in the nvim data/sessions directory (~/.local/share/nvim/sessions on a Unix-like system)

require("sessions").setup({
    events = { "WinEnter" },
    session_filepath = vim.fn.stdpath("data") .. "/sessions",
    absolute = true,
})

This version is compatible with Neovim 0.6 and newer.

Commands

The setup function registers the following commands:

See :h sessions-usage for more information on the commands.

Lua API

The session commands may also be accessed from Lua:

local sessions = require("sessions")

sessions.save(path: string, opts: table)

sessions.load(path: string, opts: table)

sessions.start_autosave()

sessions.stop_autosave(opts: table)

sessions.recording(): bool

See :h sessions-api for more information on the Lua API.

Demo

https://user-images.githubusercontent.com/7967463/151680092-71963df1-6459-4a57-bea9-a53e2a16fb2c.mp4

In this demo video I create a sessions file at .nvim/session relative to my current directory. I then repeatedly quit nvim, reopen and load the session, modify the layout, and close nvim. Halfway through I no longer provide a path to :SessionsLoad because I have configured my session_filepath to be ".nvim/session".

Related

If you want a more automatic solution, or something else, these plugins may interest you: