olimorris/persisted.nvim

github github
session
star 38
stars
alert-circle 1
open issues
users 1
subscribers
git-branch 3
forks
CREATED

2021-09-07

UPDATED

22 hours ago


:floppy_disk: Persisted

MIT License Tests

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.

:book: Table of Contents

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

:zap: Requirements

  • Neovim >= 0.6.0

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

:wrench: 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 = nil, -- function to run before the session is saved to disk
  after_save = nil, -- function to run after the session is saved to disk
  telescope = { -- options for the telescope extension
    before_source = nil, -- function to run before the session is sourced via telescope
    after_source = nil, -- 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()
    print("Session was saved!")
  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

The plugin allows for an after callback to be executed in relation to a session being sourced:

require("persisted").setup({
  after_source = function()
    -- Reload the LSP servers
    vim.lsp.stop_client(vim.lsp.get_active_clients())
  end
})

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
      -- Thanks to https://github.com/avently
      vim.api.nvim_input("<ESC>:%bd<CR>")
    end,
    after_source = function(session)
      -- Change the git branch
      print("Loaded session " .. session.name)
    end,
  },
})

The callbacks can accept a session parameter which is a table that has the following properties:

  • name - The filename of the session.
  • file_path - The file path to the session.

:rocket: 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 session file
  • <C-d> - Delete the 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.

:page_with_curl: License

MIT