Session Management in Neovim

The retro arcade image can't help but remind me of managing sessions in Neovim. You can almost imagine each arcade as a separate project with different buffers open. They have their own state with their own panes.

If that were the case, we could simply slide our chair from one arcade to the next, and all those panes and buffers would still be there, waiting. That sounds pretty nice, right?

Now, each time we open Neovim in a directory, we have to set up the panes again, open the files we were working on, and get back into a flow state. If there's anything Neovim users want, it's to avoid doing anything that gets them out of that state.

Using the mouse? That means taking my hands off the keyboard!

So how can we do that easily without thinking? Without really much configuration?

Like with most things in Neovim, "there's a plugin for that"™. And that plugin, is https://github.com/rmagatti/auto-session.

The Setup

Let's open up a new lua file in ~/.config/nvim/lua/plugins directory called auto-session.lua.

The setup (no pun intended) is pretty straightforward.

return {
  "rmagatti/auto-session",
  config = function()
    require("auto-session").setup()
  end,
}

Here, we add a Lua table that includes the Github short URL followed by a config function that simply requires the plugin and calls setup() on it. If we close Neovim and relaunch it, you'll see the plugin is installed.

So, how does this new arcade machine work? It's pretty simple. Go to a project on your computer and launch nvim.

1. Open a file in the project
2. Split the window into 2 panes with :split
3. Open another file in the 2nd pane

Normally, if you quit out of Neovim and relaunched it, you'd be looking at an empty buffer. We don't want that! We want the files that we had open to still be open.

First, let's quit all with :qa. Without changing directories, relaunch nvim. Each of your panes should still be there with the files open!

How does it work?

Whenever you open up Neovim in a directory, a session is created in in ~/.local/share/nvim/sessions. The file name is the directory + .vim. Every time you load nvim, it will look this file to get you into the same state you were in previously.

There is a ton of configuration you can do so if you want to expand beyond the basics, look here.

Navigating Sessions within Neovim

This is pretty cool but what if I wanted to be able to navigate between sessions without having to exit Neovim, change directories, and launch Neovim again?

With a couple tweaks to our config, we can do just that with Telescope.

return {
  "rmagatti/auto-session",
  config = function()
    require("auto-session").setup {
      auto_session_suppress_dirs = { "~/", "~/Projects", "~/Downloads", "/" },
      session_lens = {
        buftypes_to_ignore = {}, 
        load_on_setup = true,
        theme_conf = { border = true },
        previewer = false,
      },
    }

    vim.keymap.set("n", "<Leader>ls", require("auto-session.session-lens").search_session, {
      noremap = true,
    })
  end,
}

We've added a few things to our config. Specifically, we're suppressing some directories with auto_session_suppress_dirs. From there, we add session_lens. This is what allows us to view our sessions from within Neovim.

Of course, we need to set up a keymap. With our last lines, we set up <Leader>ls to trigger our session window viewer. Using the arrow keys, we can navigate to the session we want to hop into. It even has a built-in search!

Should I use Auto-session ?

If you only use Neovim without a terminal multiplexer like Zellij or Tmux, then this could be a good tool to manage your sessions. It's pretty lightweight to do what it does and can seamlessly integrate with your current workflow without much effort.

However, if you do use either Zellij or Tmux, you're better off using their session management tool solutions. We cover both of these in detail so you can make the choice that makes the most sense for you.

We've linked to both if you want to get into the terminal multiplexer game, whether that's Zellij or Tmux. We recommend it!

Zellij

Tmux