persisted.nvim

You can control where persisted.nvim automatically starts or loads sessions using allowed_dirs and ignored_dirs.

Allowed Directories: Specifying a directory in allowed_dirs will cause the plugin to start and autoload from that directory and all its sub-directories.

allowed_dirs = {
  "~/.dotfiles",
  "~/Code",
}

Ignored Directories: Directories in ignored_dirs will never be used for starting or autoloading. By default, this ignores the directory and all its children. To ignore only an exact directory match, use the { "path", exact = true } syntax.

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

You can implement custom logic to decide when a session should be automatically loaded. For example, you can use a VimEnter autocmd to check if Neovim was started with specific arguments or if it's a directory, and then call persisted.autoload({ force = true }) accordingly.

local persisted = require("persisted")
vim.api.nvim_create_autocmd("VimEnter", {
  nested = true,
  callback = function()
    if vim.g.started_with_stdin then
      return
    end

    local forceload = false
    if vim.fn.argc() == 0 then
      forceload = true
    elseif vim.fn.argc() == 1 then
      local dir = vim.fn.expand(vim.fn.argv(0))
      if dir == '.' then
        dir = vim.fn.getcwd()
      end

      if vim.fn.isdirectory(dir) ~= 0 then
        forceload = true
      end
    end

    persisted.autoload({ force = forceload })
  end,
})

To manage sessions via Telescope, you must load the extension in your Telescope configuration:

require("telescope").load_extension("persisted")

You can also customize the Telescope layout specifically for the persisted extension:

require('telescope').setup({
  extensions = {
    persisted = {
      layout_config = { width = 0.55, height = 0.55 }
    }
  }
})

Install and configure persisted.nvim using your preferred Neovim package manager. For lazy.nvim, it is recommended to use the BufReadPre event to ensure the plugin loads only when a buffer is loaded.

-- Lazy.nvim
{
  "olimorris/persisted.nvim",
  event = "BufReadPre",
  opts = {
    -- Your config goes here ...
  },
}

Open the session picker using :Telescope persisted. While navigating the picker, use the following default mappings:

• <CR> - Open/source the session file
• <C-b> - Add/update the git branch for the session file
• <C-c> - Copy the session file
• <C-d> - Delete the session file

If you invoke Neovim from a sub-directory, the default git branch detection might fail. You can override persisted.branch with a custom function that uses git branch --show-current to ensure the correct branch is used for session naming.

{
  "olimorris/persisted.nvim",
  lazy = false,
  opts = {
    autoload = true,
    autosave = true,
    use_git_branch = true,
  },
  config = function(_, opts)
    local persisted = require("persisted")
    persisted.branch = function()
      local branch = vim.fn.systemlist("git branch --show-current")[1]
      return vim.v.shell_error == 0 and branch or nil
    end
    persisted.setup(opts)
  end,
}

To prevent certain branches (e.g., feature or bugfix branches) from being saved as sessions, you can check the current branch against an ignored list before calling persisted.start() in your configuration.

{
  "olimorris/persisted.nvim",
  lazy = false,
  opts = {
    autostart = true,
    use_git_branch = true,
  },
  config = function(_, opts)
    local persisted = require("persisted")
    local utils = require("persisted.utils")
    local ignored_branches = {
      "feature_branch",
      "bug_fix_branch"
    }

    persisted.setup(opts)

    -- Only start the plugin if the branch isn't in the ignored list
    if not utils.in_table(persisted.branch(), ignored_branches) then
      persisted.start()
    end
  end
}

You can create an autocmd for the User event with the pattern PersistedDeletePost to perform actions (like showing a notification) whenever a session is deleted. The event.data.path field contains the path of the deleted session.

local persisted = require("persisted").setup()

vim.api.nvim_create_autocmd("User", {
  pattern = "PersistedDeletePost",
  callback = function(event)
    vim.notify("Session `'\" .. event.data.path .. "\" deleted")
  end,
})

The plugin provides several commands to manage sessions manually:

• :Persisted toggle - Determines whether to load, start or stop a session
• :Persisted start - Start recording a session (useful if autostart = false)
• :Persisted stop - Stop recording a session
• :Persisted save - Save the current session
• :Persisted select - Load a session from a list (alternative to Telescope)
• :Persisted load - Load the session for the current directory and current branch (if use_git_branch = true)
• :Persisted load_last - Load the most recent session
• :Persisted delete - Delete a session from a list
• :Persisted delete_current - Delete the current session