lukaspietzschmann / sessions.nvim

a simple session manager plugin

sessions.nvim

This is my take on natecraddock's sessions.nvim plugin. Full credit to him, for coming up with this project. I only changed a few lines.

This project differs from the original in that here all session-files can be saved in one central folder.

---

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

• The commands :SessionsSave and :SessionsLoad are used to save and load session files.
• Further changes to the session are automatically saved to the session file after saving or loading a session.
• Session files created with sessions.nvim are independent of the plugin; loading with nvim -S or :source will not start autosaving.
• A default session base-path may be customized.

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.

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

Example Usage

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

Later return to the same path and open nvim. Run :SessionsLoad project-name 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 base-path
    --
    -- every session-file is stored in this directory
    session_base_path = vim.fn.resolve(vim.fn.stdpath('data') .. '/' .. 'sessions'),
}

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 directory:

require'sessions'.setup{
    events = { 'WinEnter' },
    session_filepath = '~/.nvim/session/',
}

Commands

The setup function registers the following commands:

• :SessionsSave[!] name

  Save a session file to the base-path with the given name. If the name exists it will be overwritten. Starts autosaving the session on the configured events.

• :SessionsLoad[!] name

  Load a session file with the given name from the base-path. If the file does not exist no session will be loaded. Starts autosaving changes to the session after loading.

• :SessionsStop[!]

  Stops session autosaving if enabled. The current state will be saved before stopping.

• :SessionsDelete name Delete a session file with the given name from the base-path. If the file does not exist an error is emitted

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(name: string, opts: table)

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

sessions.delete(name: string)

sessions.stop_autosave(opts: table)

sessions.recording(): bool

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

Integration with other tools

telescope.nvim

With telescope-sessions you can use telescope.nvim to select open a session.

The command :Telescope telescope-sessions search_sessions opens a picker that displays all sessions under your base-path. I've mapped this command to <A-o> with vim.keymap.set('n', '<A-o>', '<cmd>Telescopetelescope-sessions search_sessions<CR>')

fzf

I setup the following function that lets me select a project and automatically opens it with neovim:

se() {
	local name
	name=$(ls -1 /home/luke/.local/share/nvim/sessions | fzf) && nvim -c "SessionsLoad $name"
}

You have to change /home/luke/.local/share/nvim/sessions to whatever your base-path is set to!