💾 Persisted

Persisted is a simple lua plugin for automated session management within Neovim.

The plugin was forked from the fantastic Persistence.nvim as active development seems to have been paused and there were some useful pull requests.

📖 Table of Contents

• Features
• Requirements
• Installation
• Configuration
  • Defaults
  • Session options
  • Session save location
  • Git branching
  • Autosaving
  • Autoloading
  • Allowed directories
  • Ignored directories
  • Callbacks
  • Telescope extension
• Usage
  • Commands
  • Lazy loading
  • Helpers
• License

✨ Features

• Automatically saves the active session under .local/share/nvim/sessions on exiting Neovim
• Supports sessions across multiple git branches
• Supports auto saving and loading of sessions with allowed/ignored directories
• Simple API to save/stop/restore/delete/list the current session(s)
• Telescope extension to list all sessions

⚡ Requirements

• Neovim >= 0.6.0

📦 Installation

Install the plugin with your preferred package manager:

packer

-- Lua
use({
  "olimorris/persisted.nvim",
  --module = "persisted", -- For lazy loading
  config = function()
    require("persisted").setup()
    require("telescope").load_extension("persisted") -- To load the telescope extension
  end,
})

vim-plug

" Vim Script
Plug 'olimorris/persisted.nvim'

lua << EOF
  require("persisted").setup {
    -- your configuration comes here
    -- or leave it empty to use the default settings
    -- refer to the configuration section below
  }
EOF

🔧 Configuration

Defaults

The plugin comes with the following defaults:

{
  dir = vim.fn.expand(vim.fn.stdpath("data") .. "/sessions/"), -- directory where session files are saved
  use_git_branch = false, -- create session files based on the branch of the git enabled repository
  autosave = true, -- automatically save session files when exiting Neovim
  autoload = false, -- automatically load the session for the cwd on Neovim startup
  allowed_dirs = nil, -- table of dirs that the plugin will auto-save and auto-load from
  ignored_dirs = nil, -- table of dirs that are ignored when auto-saving and auto-loading
  before_save = function() end, -- function to run before the session is saved to disk
  after_save = function() end, -- function to run after the session is saved to disk
  telescope = { -- options for the telescope extension
    before_source = function(session) end, -- function to run before the session is sourced via telescope
    after_source = function(session) end, -- function to run after the session is sourced via telescope
  },
}

Session options

As the plugin uses Vim's :mksession command then you may change the vim.o.sessionoptions value to determine what to write into the session. Please see :h sessionoptions for more information.

Note: The author uses vim.o.sessionoptions = "buffers,curdir,folds,winpos,winsize"

Session save location

The location of the saved files for the sessions may be changed by altering the dir configuration option. By default, the plugin will save to ~/.local/share/nvim/sessions.

Note: If you change the dir value and try to restore sessions, the plugin will be unable to find existing ones

Git branching

One of the plugin's core features is the ability to have multiple sessions files for a given project, by using git branches. To enable git branching, set use_git_branch = true.

Note: If git branching is enabled on a non git enabled repo, then main will be used as the default branch

Autosaving

By default, the plugin will automatically save a Neovim session to disk. This action is only undertaken when the user quits Neovim. This can be turned off by setting autosave = false.

Autosaving can be further controlled by specifying allowed_dirs and ignored_dirs.

Autoloading

The plugin can be enabled to automatically load sessions when Neovim is started. Whilst off by default, this can be turned on by setting autoload = true.

Autoloading can be further controlled by specifying allowed_dirs and ignored_dirs.

Note: Autoloading will not occur if a user opens Neovim with arguments such as nvim some_file.rb

Allowed directories

You may specify a table of directories for which the plugin will autosave and/or autoload from. For example:

{
  allowed_dirs = {
    "~/Code/Neovim",
    "~/Code/Projects/Ruby
  }
}

Note: If allowed_dirs is set, then the plugin will only autosave and/or autoload from the specificed directories

Note: If allowed_dirs is left at its default value and autosave and/or autoload are set to true, then the plugin will autoload/autosave from any directory

Ignored directories

You may specify a table of directories for which the plugin will never autosave and autoload from. For example:

{
  ignored_dirs = {
    "~/.config",
    "~/.local/nvim"
  }
}

Callbacks

The plugin allows for before and after callbacks to be executed before and after a session is saved. This is achieved via the before_save and after_save configuration options. For example:

{
  before_save = function()
    pcall(vim.cmd, "bw minimap")
  end,
}

Note: The author uses a before callback to ensure that minimap.vim is not written into the session. Its presence prevents the exact buffer and cursor position from being restored when loading a session

Telescope extension

This feature is still in beta!!

The plugin contains an extension for telescope.nvim which allows the user to list all of the saved session files and source them.

Telescope callbacks

The plugin allows for before and after callbacks to be used when sourcing a session via Telescope. For example:

{
  telescope = {
    before_source = function()
      -- Close all open buffers
      pcall(vim.cmd, "bufdo bwipeout")
    end,
    after_source = function(session)
      print("Session " .. session.name .. " loaded for the " .. session.branch .. " branch")
    end,
  },
}

A session table is exposed to the callback functions and has the following properties:

• name - The filename of the session.
• branch - The git branch of the session.
• pwd - The present working directory of the session; and
• file_path - The file path to the session.

🚀 Usage

Default commands

The plugin comes with a number of commands:

• SessionStart - Start recording a session. Useful if autosave = false
• SessionStop - Stop recording a session
• SessionSave - Save the current session
• SessionLoad - Load the session for the current directory and current branch if git_use_branch = true
• SessionLoadLast - Load the last session
• SessionDelete - Delete the current session
• SessionToggle - Determines whether to load, start or stop a session

Note: The author only binds SessionToggle to a keymap for simplicity.

Telescope extension

The Telescope extension may be opened via :Telescope persisted.

Once opened, the available keymaps are:

• <CR> - Source the selected session file

Lazy loading

The plugin is designed to work with startup screens like vim-startify or dashboard out of the box. It will never load a session automatically by default.

However, to lazy load the plugin add the module = "persisted" line to packer.

Helpers

The plugin sets a global variable, vim.g.persisting, which is set to true when a session is started. The author uses this to display an icon in their statusline.

📃 License

MIT