• Stars
    star
    226
  • Rank 176,514 (Top 4 %)
  • Language
    Lua
  • License
    MIT License
  • Created about 2 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A replacement for mksession with a better API

resession.nvim

A replacement for :mksession with a better API

  • No magic behavior. Only does what you tell it.
  • Supports tab-scoped sessions.
  • Extensive customizability in what gets saved/restored.
  • Easy to write extensions for other plugins.

Requirements

  • Neovim 0.8+

Installation

resession supports all the usual plugin managers

lazy.nvim
{
  'stevearc/resession.nvim',
  opts = {},
}
Packer
require("packer").startup(function()
  use({
    "stevearc/resession.nvim",
    config = function()
      require("resession").setup()
    end,
  })
end)
Paq
require("paq")({
  { "stevearc/resession.nvim" },
})
Neovim native package
git clone --depth=1 https://github.com/stevearc/resession.nvim.git \
  "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/resession/start/resession.nvim

Quick start

local resession = require("resession")
resession.setup()
-- Resession does NOTHING automagically, so we have to set up some keymaps
vim.keymap.set("n", "<leader>ss", resession.save)
vim.keymap.set("n", "<leader>sl", resession.load)
vim.keymap.set("n", "<leader>sd", resession.delete)

Now you can use <leader>ss to save a session. When you want to load a session, use <leader>sl.

Guides

Automatically save a session when you exit Neovim

vim.api.nvim_create_autocmd("VimLeavePre", {
  callback = function()
    -- Always save a special session named "last"
    resession.save("last")
  end,
})

Periodically save the current session

When you are attached to a session (have saved or loaded a session), use this config to periodically re-save that session in the background.

require("resession").setup({
  autosave = {
    enabled = true,
    interval = 60,
    notify = true,
  },
})

Create one session per directory

Load a dir-specific session when you open Neovim, save it when you exit.

vim.api.nvim_create_autocmd("VimEnter", {
  callback = function()
    -- Only load the session if nvim was started with no args
    if vim.fn.argc(-1) == 0 then
      -- Save these to a different directory, so our manual sessions don't get polluted
      resession.load(vim.fn.getcwd(), { dir = "dirsession", silence_errors = true })
    end
  end,
})
vim.api.nvim_create_autocmd("VimLeavePre", {
  callback = function()
    resession.save(vim.fn.getcwd(), { dir = "dirsession", notify = false })
  end,
})

Create one session per git branch

Same as above, but have a separate session for each git branch in a directory.

local function get_session_name()
  local name = vim.fn.getcwd()
  local branch = vim.trim(vim.fn.system("git branch --show-current"))
  if vim.v.shell_error == 0 then
    return name .. branch
  else
    return name
  end
end
vim.api.nvim_create_autocmd("VimEnter", {
  callback = function()
    -- Only load the session if nvim was started with no args
    if vim.fn.argc(-1) == 0 then
      resession.load(get_session_name(), { dir = "dirsession", silence_errors = true })
    end
  end,
})
vim.api.nvim_create_autocmd("VimLeavePre", {
  callback = function()
    resession.save(get_session_name(), { dir = "dirsession", notify = false })
  end,
})

Use tab-scoped sessions

When saving a session, only save the current tab

-- Bind `save_tab` instead of `save`
vim.keymap.set("n", "<leader>ss", resession.save_tab)
vim.keymap.set("n", "<leader>sl", resession.load)
vim.keymap.set("n", "<leader>sd", resession.delete)

This will save only the current tabpage layout, but will save all of the open buffers. You can provide a filter to exclude buffers. For example, if you are using :tcd to have tabs open for different directories, this will only save buffers in the current tabpage directory:

require("resession").setup({
  tab_buf_filter = function(tabpage, bufnr)
    local dir = vim.fn.getcwd(-1, vim.api.nvim_tabpage_get_number(tabpage))
    -- ensure dir has trailing /
    dir = dir:sub(-1) ~= "/" and dir .. "/" or dir
    return vim.startswith(vim.api.nvim_buf_get_name(bufnr), dir)
  end,
})

Saving custom data with an extension

To create an extension, create a file in your runtimepath at lua/resession/extensions/myplugin.lua. Add the following contents:

local M = {}

---Get the saved data for this extension
---@param opts resession.Extension.OnSaveOpts Information about the session being saved
---@return any
M.on_save = function(opts)
  return {}
end

---Restore the extension state
---@param data The value returned from on_save
M.on_pre_load = function(data)
  -- This is run before the buffers, windows, and tabs are restored
end

---Restore the extension state
---@param data The value returned from on_save
M.on_post_load = function(data)
  -- This is run after the buffers, windows, and tabs are restored
end

---Called when resession gets configured
---This function is optional
---@param data table The configuration data passed in the config
M.config = function(data)
  --
end

---Check if a window is supported by this extension
---This function is optional, but if provided save_win and load_win must
---also be present.
---@param winid integer
---@param bufnr integer
---@return boolean
M.is_win_supported = function(winid, bufnr)
  return true
end

---Save data for a window
---@param winid integer
---@return any
M.save_win = function(winid)
  -- This is used to save the data for a specific window that contains a non-file buffer (e.g. a filetree).
  return {}
end

---Called with the data from save_win
---@param winid integer
---@param config any
---@return integer|nil If the original window has been replaced, return the new ID that should replace it
M.load_win = function(winid, config)
  -- Restore the window from the config
end

return M

Then to activate it, users can add the extension to their call to setup:

require("resession").setup({
  extensions = {
    myplugin = {
      -- these args will get passed in to M.config()
    },
  },
})

For tab-scoped sessions, the on_save and on_load methods of extensions will be disabled by default. There is a special config argument always available that can override this:

require("resession").setup({
  extensions = {
    myplugin = {
      enable_in_tab = true,
    },
  },
})

Refer to the quickfix extension for a complete example.

Setup options

require("resession").setup({
  -- Options for automatically saving sessions on a timer
  autosave = {
    enabled = false,
    -- How often to save (in seconds)
    interval = 60,
    -- Notify when autosaved
    notify = true,
  },
  -- Save and restore these options
  options = {
    "binary",
    "bufhidden",
    "buflisted",
    "cmdheight",
    "diff",
    "filetype",
    "modifiable",
    "previewwindow",
    "readonly",
    "scrollbind",
    "winfixheight",
    "winfixwidth",
  },
  -- Custom logic for determining if the buffer should be included
  buf_filter = require("resession").default_buf_filter,
  -- Custom logic for determining if a buffer should be included in a tab-scoped session
  tab_buf_filter = function(tabpage, bufnr)
    return true
  end,
  -- The name of the directory to store sessions in
  dir = "session",
  -- Show more detail about the sessions when selecting one to load.
  -- Disable if it causes lag.
  load_detail = true,
  -- List order ["modification_time", "creation_time", "filename"]
  load_order = "modification_time",
  -- Configuration for extensions
  extensions = {
    quickfix = {},
  },
})

API

setup(config)

setup(config)
Initialize resession with configuration options

Param Type Desc
config table

load_extension(name, opts)

load_extension(name, opts)
Load an extension some time after calling setup()

Param Type Desc
name string Name of the extension
opts table Configuration options for extension

get_current()

get_current(): string
Get the name of the current session

Returns:

Type Desc
string ?

get_current_session_info()

get_current_session_info(): nil|resession.SessionInfo
Get information about the current session

detach()

detach()
Detach from the current session

list(opts)

list(opts): string[]
List all available saved sessions

Param Type Desc
opts nil|resession.ListOpts
dir nil|string Name of directory to list (overrides config.dir)

delete(name, opts)

delete(name, opts)
Delete a saved session

Param Type Desc
name nil|string If not provided, prompt for session to delete
opts nil|resession.DeleteOpts
dir nil|string Name of directory to delete from (overrides config.dir)

save(name, opts)

save(name, opts)
Save a session to disk

Param Type Desc
name nil|string
opts nil|resession.SaveOpts
attach nil|boolean Stay attached to session after saving (default true)
notify nil|boolean Notify on success
dir nil|string Name of directory to save to (overrides config.dir)

save_tab(name, opts)

save_tab(name, opts)
Save a tab-scoped session

Param Type Desc
name nil|string If not provided, will prompt user for session name
opts nil|resession.SaveOpts
attach nil|boolean Stay attached to session after saving (default true)
notify nil|boolean Notify on success
dir nil|string Name of directory to save to (overrides config.dir)

save_all(opts)

save_all(opts)
Save all current sessions to disk

Param Type Desc
opts nil|table
notify nil|boolean

load(name, opts)

load(name, opts)
Load a session

Param Type Desc
name nil|string
opts nil|resession.LoadOpts
attach nil|boolean Stay attached to session after loading (default true)
reset nil|boolean|"auto" Close everything before loading the session (default "auto")
silence_errors nil|boolean Don't error when trying to load a missing session
dir nil|string Name of directory to load from (overrides config.dir)

Note:

The default value of `reset = "auto"` will reset when loading a normal session, but _not_ when
loading a tab-scoped session.

add_hook(name, callback)

add_hook(name, callback)
Add a callback that runs at a specific time

Param Type Desc
name "pre_save"|"post_save"|"pre_load"|"post_load"
callback fun(...: any)

remove_hook(name, callback)

remove_hook(name, callback)
Remove a hook callback

Param Type Desc
name "pre_save"|"post_save"|"pre_load"|"post_load"
callback fun(...: any)

default_buf_filter(bufnr)

default_buf_filter(bufnr): boolean
The default config.buf_filter (takes all buflisted files with "", "acwrite", or "help" buftype)

Param Type Desc
bufnr integer

is_loading()

is_loading(): boolean
Returns true if a session is currently being loaded

Extensions

FAQ

Q: Why another session plugin?

A: All the other plugins use :mksession under the hood

Q: Why don't you want to use :mksession?

A: While it's amazing that this feature is built-in to vim, and it does an impressively good job for most situations, it is very difficult to customize. If :help sessionoptions covers your use case, then you're golden. If you want anything else, you're out of luck.

More Repositories

1

oil.nvim

Neovim file explorer: edit your filesystem like a buffer
Lua
3,907
star
2

conform.nvim

Lightweight yet powerful formatter plugin for Neovim
Lua
3,073
star
3

dressing.nvim

Neovim plugin to improve the default vim.ui interfaces
Lua
1,844
star
4

aerial.nvim

Neovim plugin for a code outline window
Lua
1,711
star
5

overseer.nvim

A task runner and job management plugin for Neovim
Lua
1,193
star
6

pypicloud

S3-backed pypi server implementation
Python
505
star
7

vim-arduino

Vim plugin for compiling and uploading arduino sketches
Vim Script
345
star
8

quicker.nvim

Improved UI and workflow for the Neovim quickfix
Lua
321
star
9

stickybuf.nvim

Neovim plugin for locking a buffer to a window
Lua
246
star
10

gkeep.nvim

Google Keep integration for Neovim
Python
193
star
11

dql

A SQL-ish language for DynamoDB
Python
149
star
12

flywheel

Object mapper for Amazon's DynamoDB
Python
128
star
13

profile.nvim

lua profiler for nvim
Lua
126
star
14

qf_helper.nvim

A collection of improvements for the quickfix buffer
Lua
97
star
15

pypicloud-docker

Docker image for pypicloud
Shell
86
star
16

dotfiles

Lua
57
star
17

godot_parser

Python library for parsing Godot scene files
Python
54
star
18

pair-ls

Editor-agnostic remote pair programming
TypeScript
28
star
19

three.nvim

Neovim plugin for working with buffers, windows, and tabs
Lua
21
star
20

nvim-typecheck-action

Github action for typechecking a neovim plugin
Lua
17
star
21

pair-ls.nvim

Neovim plugin for pair-ls
Lua
14
star
22

dynamo3

Python 3 compatible library for DynamoDB
Python
13
star
23

gitstack

A utility for stacking branches and github pull requests
Python
12
star
24

pyramid_webpack

Pyramid extension for managing assets with Webpack
Python
10
star
25

vim-vscode-snippets

A collection of vscode snippets for vim
Python
9
star
26

nvim_doc_tools

Python scripts for Neovim documentation generation
Python
7
star
27

pyramid_duh

Utilities that you'll want for nearly every pyramid app
Python
6
star
28

Battlecode-Server-Tester

Distributed testing tool for the MIT Battlecode competition
Java
3
star
29

parseargs

Bash utility for parsing commandline arguments
Shell
2
star
30

pike

Asset pipeline and make tool
Go
2
star
31

pair-ls-vscode

VS Code extension for pair-ls
TypeScript
2
star
32

eat_your_vegetables

An organizational wrapper around celery
Python
2
star
33

bluepill

A command line utility for working inside docker containers
Python
2
star
34

pore

Command line full-text search
Rust
2
star
35

flow-coverage.nvim

Neovim plugin to display flow type coverage information
Lua
2
star
36

stevearc

1
star
37

stevetags

Little website for tagging Dropbox files
Python
1
star