Skip to main content

Sessions & Workspace

Session Management (persistence.nvim)​

LazyVim uses persistence.nvim to automatically save and restore your editing sessions. This means your buffers, window layout, and cursor positions are preserved between restarts.

How It Works​

  • Auto-save: Every time you close Neovim, the current session is saved
  • Auto-restore: When you reopen Neovim, the last session is restored
  • Background saving: Sessions are saved periodically in the background

Session Keys​

KeyAction
<leader>qsRestore the last saved session
<leader>qlRestore the last session (even if it was manually stopped)
<leader>qSSelect a session to restore from a list
<leader>qdStop saving the current session (don't persist it)

Session Commands​

:lua require("persistence").load()              " Restore last session
:lua require("persistence").load({ last = true }) " Restore last session (always)
:lua require("persistence").select()            " Pick session from list
:lua require("persistence").stop()              " Stop saving current session
:lua require("persistence").start()             " Resume saving

Session Storage Location​

Sessions are stored at:

~/.local/share/nvim/sessions/

You can delete individual session files here if a session is corrupted:

rm ~/.local/share/nvim/sessions/*.lua

Session Workflows​

Daily Start​

1. nvim                  ← Opens with dashboard or restores last session
2. Press s on dashboard  ← Restore last session
3. All buffers/layouts   ← Previous state is recovered

Multiple Projects​

Project A session saved:  <leader>qd   ← Stop saving project A
Open project B:            nvim ~/project-b
Session B auto-saves on quit
Switch back to project A: <leader>qs   ← Project A session restored

Session Without Saving​

If you are exploring and don't want to persist the session:

<leader>qd    ← Stop session tracking
:qa!          ← Quit without saving session state

Root Directory Detection​

LazyVim detects the project root automatically. This affects all operations that are scoped to "Root Dir" (find files, grep, terminal, git, etc.).

How Root Is Detected​

vim.g.root_spec = { "lsp", { ".git", "lua" }, "cwd" }

Detection order:

  1. LSP root — If an LSP server is attached, use its root directory
  2. Marker files — Look for .git or lua directory
  3. cwd — Fall back to the current working directory

Check Current Root​

:lua print(LazyVim.root())

Override Root for a Buffer​

:lua LazyVim.root.set_buffer_root("/path/to/project")

Custom Root Detection​

lua/config/options.lua
-- Add custom root markers
vim.g.root_spec = { "lsp", { ".git", "lua", "package.json", "Makefile", "Cargo.toml" }, "cwd" }

-- Ignore certain LSP servers for root detection
vim.g.root_lsp_ignore = { "copilot", "tailwindcss" }

Workspace with LSP​

When working with multiple projects in the same Neovim instance:

<leader>lwa    " Add a workspace folder
<leader>lwA    " Remove a workspace folder

This adds the directory to LSP's workspace folders, enabling cross-project symbol search.

Project Switcher​

Use <leader>fp to open the projects picker. This shows recently used project directories.

<leader>fp    ← Pick a recent project to switch to

Snacks Scratch Buffer​

Temporary scratch buffers for quick notes:

<leader>.     ← Toggle a scratch buffer
<leader>S     ← Select from existing scratch buffers

Terminal Sessions​

Terminal buffers are also tracked in sessions. When you restore a session, previously open terminals are restored with their working directories.

Session Best Practices​

ScenarioAction
Daily workJust nvim → s on dashboard to restore
Quick file editnvim file.txt — no session needed
Different projectnvim → <leader>qs after opening the other project
Temporary exploration<leader>qd then :qa!
Corrupted sessionDelete ~/.local/share/nvim/sessions/
Keep buffers but reset layout:lua require('persistence').load()

Managing Sessions Manually​

If you want full control over sessions:

lua/plugins/persistence.lua
return {
  "folke/persistence.nvim",
  opts = {
    -- Only save sessions when explicitly asked
    save_dir = vim.fn.stdpath("data") .. "/sessions/",
    options = {
      "buffers", "curdir", "tabpages", "winsize",
      "help", "globals", "skiprtp", "folds",
    },
  },
}