auto-session

By default, AutoSession does not track cwd changes. When enabled via cwd_change_handling = true, changing the directory with :cd triggers a workflow:

1. Pre-change: Saves the current session, clears all buffers (%bw!), clears jumps, and runs pre_cwd_changed_cmds.
2. Post-change: Restores the session for the new cwd and runs post_cwd_changed_cmds.

This prevents buffer/jump bleeding between different project sessions.

opts = {
  cwd_change_handling = true,

  pre_cwd_changed_cmds = {
    "tabdo NERDTreeClose", -- Close NERDTree before saving session
  },

  post_cwd_changed_cmds = {
    function()
      require("lualine").refresh() -- example refreshing the lualine status line _after_ the cwd changes
    end,
  },
}

AutoSession automates the management of your workspace state based on your current working directory (cwd):

1. On Startup: AutoSession checks if a session exists for the current cwd. If found, it reopens all buffers and windows associated with that directory.
2. On Exit: When you quit Neovim, AutoSession automatically saves a session for the current cwd so you can resume your work later.

This behavior can be customized using auto_save, auto_restore, and auto_create settings.

If you are not using lazy.nvim, you must manually call the .setup() method to initialize the plugin. For example:

require("auto-session").setup({})

For the best experience with session restoration (including folds, terminals, and window positions), it is recommended to update your Neovim sessionoptions setting.

-- Lua
vim.o.sessionoptions = "blank,buffers,curdir,folds,help,tabpages,winsize,winpos,terminal,localoptions"

Or using VimL:

set sessionoptions+=winpos,terminal,folds

To install AutoSession using the lazy.nvim plugin manager, add the following configuration to your plugin list. Setting lazy = false is required to ensure sessions are restored correctly on startup. You can configure suppressed_dirs to prevent session creation in specific directories like your home folder or downloads.

return {
  "rmagatti/auto-session",
  lazy = false,

  ---enables autocomplete for opts
  ---@module "auto-session"
  ---@type AutoSession.Config
  opts = {
    suppressed_dirs = { "~/", "~/Projects", "~/Downloads", "/" },
    -- log_level = 'debug',
  },
}

If you need to disable AutoSession based on specific conditions (e.g., when using Firenvim or VSCode), you can use the following methods:

1. Using a plugin manager (e.g., lazy.nvim): Use the cond property to prevent the plugin from loading.

2. Using VimScript: Set the g:auto_session_enabled global variable to v:false.

3. Using CLI flag: Pass the command directly when starting Neovim.

-- lazy.nvim example
return {
  "rmagatti/auto-session",
  lazy = false,
  cond = not vim.g.started_by_firenvim and not vim.g.vscode,
}

" VimScript example
if exists('g:started_by_firenvim')
  let g:auto_session_enabled = v:false
endif

# CLI example
nvim --cmd "let g:auto_session_enabled = v:false"

AutoSession can integrate with Git to improve session naming and restoration:

• git_use_branch_name = true: Includes the current Git branch in the session name.
• git_auto_restore_on_branch_change = true: Automatically restores the session associated with the branch you just switched to. If you have modified files, AutoSession will prompt you to close them before restoring.

opts = {
  git_use_branch_name = true,
  git_auto_restore_on_branch_change = true,
}

You can restrict where AutoSession automatically saves sessions using allowed_dirs and suppressed_dirs. Both accept tables of strings and support glob patterns.

• allowed_dirs: If set, sessions are only auto-saved in matching directories.
• suppressed_dirs: If set, sessions in these directories will never be auto-saved.

Glob Pattern Syntax

• *: Matches characters in a single directory level (e.g., /projects/* matches /projects/foo but not /projects/foo/bar).
• **: Matches characters including directory separators (e.g., /projects/** matches all subdirectories).
• ?: Matches exactly one character.
• ~: Expands to your home directory.

opts = {
  allowed_dirs = { "/some/dir/", "/projects/*", "~/work/**" },
  suppressed_dirs = { "/projects/secret" },
}

If you encounter issues with AutoSession:

1. Run :checkhealth auto-session to identify common configuration or environment problems.
2. Consult the official Wiki Troubleshooting page.
3. Check the GitHub Discussions or file an Issue.

You can persist arbitrary data (like DAP breakpoints, quickfix lists, or other plugin states) by implementing the save_extra_data and restore_extra_data functions in your configuration.

• save_extra_data(session_name): Should return a string (e.g., JSON encoded) or a table representing the data to be saved.
• restore_extra_data(session_name, extra_data): Receives the data saved by the previous function and is responsible for restoring the state.