💾 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
Usage
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:

require("persisted").setup({
  save_dir = vim.fn.expand(vim.fn.stdpath("data") .. "/sessions/"), -- directory where session files are saved
  command = "VimLeavePre", -- the autocommand for which the session is 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 session files may be changed by altering the save_dir configuration option. For example:

require("persisted").setup({
  save_dir = vim.fn.expand(vim.fn.stdpath("data") .. "/sessions/"), -- Resolves to ~/.local/share/nvim/sessions/
})

Note: The plugin may be unable to find existing sessions if the save_dir value is changed

Autocmd to save session

By default, a session is saved to disk when the VimLeavePre autocommand is triggered. This can be modified by:

require("persisted").setup({
  command = "VimLeavePre",
})

Note: See :h autocmds for more information on possible autocmds

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:

require("persisted").setup({
  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 when the VimLeavePre autocommand is triggered. Autosaving can be turned off by:

require("persisted").setup({
  autosave = false,
})

Autosaving can be further controlled for certain directories 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:

require("persisted").setup({
  autoload = true,
})

Autoloading can be further controlled for certain directories by specifying allowed_dirs and ignored_dirs.

Note: Autoloading will not occur if a user opens Neovim with arguments. For example: 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:

require("persisted").setup({
  allowed_dirs = {
    "~/.dotfiles",
    "~/Code",
  },
})

Specifying ~/Code will autosave and autoload from that directory as well as all its sub-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:

require("persisted").setup({
  ignored_dirs = {
    "~/.config",
    "~/.local/nvim"
  },
})

Specifying ~/.config will prevent any autosaving and autoloading from that directory as well as all its sub-directories.

Callbacks

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

require("persisted").setup({
  before_save = function()
    pcall(vim.cmd, "bw minimap")
  end,
  after_save = function()
    -- Do something
  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 via :Telescope persisted.

Telescope callbacks

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

require("persisted").setup({
  telescope = {
    before_source = function()
      -- Close all open buffers
      pcall(vim.cmd, "bufdo bwipeout")
    end,
    after_source = function(session)
      -- Change the git branch
      pcall(vim.cmd, "git checkout " .. session.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; 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

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

KiritchoukC/persisted.nvim