finni.nvim

███████╗██╗███╗   ██╗███╗   ██╗██╗   ███╗   ██╗██╗   ██╗██╗███╗   ███╗
██╔════╝██║████╗  ██║████╗  ██║██║   ████╗  ██║██║   ██║██║████╗ ████║
█████╗  ██║██╔██╗ ██║██╔██╗ ██║██║   ██╔██╗ ██║██║   ██║██║██╔████╔██║
██╔══╝  ██║██║╚██╗██║██║╚██╗██║██║   ██║╚██╗██║╚██╗ ██╔╝██║██║╚██╔╝██║
██║     ██║██║ ╚████║██║ ╚████║██║██╗██║ ╚████║ ╚████╔╝ ██║██║ ╚═╝ ██║
╚═╝     ╚═╝╚═╝  ╚═══╝╚═╝  ╚═══╝╚═╝╚═╝╚═╝  ╚═══╝  ╚═══╝  ╚═╝╚═╝     ╚═╝

Sublime autosessions.

A flexible, project-focused autosession plugin for Neovim, unbound by the limits of :mksession.

Introduction
✨ Features
⛓️ Dependencies
📦 Setup
🚀 Usage
👤 Concepts
❗ Limitations and caveats
⚙️ Configuration
- Defaults
- autosession
- extensions
- load
- log
- session
📒 Recipes
- Tab-scoped Sessions
- Custom Extension
🔌 API
- finni.session (Module)
- finni.auto (Module)
🧩 Extensions
- Built-in
- External
❓ FAQ

Introduction

You switched to Neovim from a less advanced™ text editor and finally learned the dark arts of exiting it. Never again shall your terminal emulator be trapped like Josef K.

Now, you urgently need to leave because your hamster has entered an Abstract Expressionist phase and is preparing to "paint" the wall with a bottle of sriracha and a toothpick. In the rush, you don't care about losing the intricate state of your 72h session and type the ancient incantation: :qa.

Neovim refuses. An unnamed buffer contains a half-formed thought that must be judged before you're allowed to go. You don't want to delete it. You don't want to commit to it. You want to protect your wall from artistic reinterpretation.

Finni just lets you leave. When you return, everything will be like you left it: Buffers, windows, tabs, jumplists, changelists, loclists, quickfix lists, and even that pesky modified buffer.

The wall, sadly, may not be.

✨ Features

Comprehensive snapshots of the current Neovim state:
- Preserve your entire workspace: tabs, window layout, open buffers, cursor positions, and relevant buffer/window/global options.
- Preserve unsaved changes and corresponding undo history, including for unnamed buffers.
- Preserve navigation state: jumplists (each window separately, unlike ShaDa), changelists, loclists, quickfix lists, including your current position in each, and buffer-local/global marks.
- Snapshot restoration is compatible with lazy.nvim VeryLazy-loaded plugins.
Automatic session management (opt-in):
- Automatically create, save, and restore snapshots per directory, Git repository and branch.
- Autoswitch sessions when changing branches (git switch) or directories (:cd).
Separate Neovim scopes, by default: directory or Git repository/branch. This prevents¹
- mangling of unrelated command/search/input/expr/debug histories.
- going back the jumplist (CTRL-o) and ending up in a seemingly random file.
Highly customizable:
- Override, filter, or extend what gets saved or restored — globally, per project, or per session.
- Add custom extensions to restore state from other plugins.
- React to events with custom hooks.
- Define scopes in code however you like: directory basename, weekday, head -c 1 /dev/random (y tho?), ...
- E.g., it's possible to (ab)use autosession loading logic to start into predefined layouts, depending on the directory you execute Neovim in.
Lua API for 'nomagic' manual session management, including tab-scoped sessions
- This API is mostly backwards-compatible with resession.nvim.
  (Finni started by forking it, a heartfelt thank you @stevearc for laying the arduous ground work! <3)
- For the brave, an even more low-level session and snapshot API (finni.core.session, finni.core.snapshot) is available.
Inbuilt pickers for snacks.picker, fzf-lua, mini.pick and telescope.nvim

⛓️ Dependencies

Neovim 0.10+
lewis6991/gitsigns.nvim (optional) for branch monitoring

📦 Setup

A general description follows. For specific plugin managers, see below.

Add this plugin to your 'runtimepath'.
(optional) Override the configuration defaults by assigning a configuration table to g:finni_config.
(optional) Enable startup autosessions by setting g:finni_autosession to true.
(optional) Define keymaps.

You don't need to call setup(). You don't need to handle lazy-loading yourself. Finni is always there for you when you need him.

`vim.pack`

vim.pack.add("https://github.com/lkubb/finni.nvim")
---@type finni.auto.InitHandler|boolean
vim.g.finni_autosession = true -- optionally enable startup autosessions
---@type finni.UserConfig
vim.g.finni_config = { --[[ custom options/overrides ]] }

`lazy.nvim`

{
  "lkubb/finni.nvim",
  -- This plugin only ever loads as much as needed.
  -- You don't need to manage lazyloading manually.
  -- Initialization is only triggered if you enable startup autosessions
  -- and an autosession is defined for the current environment
  -- or once you invoke the Finni Lua API/Ex command.
  lazy = false,
  -- If you don't want to enable startup autosessions, you can use
  --  `opts` for custom configuration (or omit it if you want to use defaults).
  init = function()
    ---@type finni.auto.InitHandler|boolean
    vim.g.finni_autosession = true -- optionally enable startup autosessions
    ---@type finni.UserConfig
    vim.g.finni_config = { --[[ custom options/overrides ]] }
  end,
}

`mini.deps`

MiniDeps.add({
  source = "lkubb/finni.nvim",
  checkout = "main",
})
---@type finni.auto.InitHandler|boolean
vim.g.finni_autosession = true -- optionally enable startup autosessions
---@type finni.UserConfig
vim.g.finni_config = { --[[ custom options/overrides ]] }

🚀 Usage

First, decide whether you want to follow a mostly hands-off approach with autosessions or prefer the more predictable route of managing your sessions manually.

Especially with autosessions, try to get an intuition for its inner workings before relying on this plugin for important work. If you prefer reading, see the Concepts section below for details on this topic.

In any case, make sure you give the limitations and caveats a quick read.

Later, you can customize the configuration and check if you want to enable some extensions to restore windows of your plugins.

Keymaps

Finni does not include default keymaps since different users will have very divergent needs and preferences. Set-and-forget startup autosession users might never need any in the first place, especially since the :Finni command exposes large parts of the Lua API for the rare case where they would want to intervene. The most useful command to map is :Finni reset, in the author's opinion.

Still, here is an example setup that focuses on autosessions:

-- Without startup autosessions, you need to enter Finni explicitly.
-- This runs the autosession logic and sets up environment monitoring.
vim.keymap.set("n", "<leader>Ss", "<cmd>Finni start<cr>", { desc = "[S]ession [S]tart" })
-- Delete active autosession, reset Neovim to a clean state and attach a fresh autosession.
vim.keymap.set("n", "<leader>SR", "<cmd>Finni reset<cr>", { desc = "[S]ession [R]eset" })
-- Detach active session. Autosessions are still triggered by environment changes.
vim.keymap.set("n", "<leader>Sd", "<cmd>Finni detach<cr>", { desc = "[S]ession [D]etach" })
-- Detach active session and stop environment monitoring.
vim.keymap.set("n", "<leader>SS", "<cmd>Finni stop<cr>", { desc = "[S]ession [S]top" })
-- List all sessions in the current project
vim.keymap.set("n", "<leader>Sl", "<cmd>Finni list<cr>", { desc = "[S]essions [L]ist" })
-- Inspect the active session
vim.keymap.set("n", "<leader>Si", "<cmd>Finni info<cr>", { desc = "[S]ession [I]nfo" })

And here is a basic one for manual sessions

-- Load a session. Displays an interactive selection.
vim.keymap.set("n", "<leader>Sl", function() require("finni.session").load() end, { desc = "[S]ession [L]oad" })
-- Save the current state to a global snapshot.
-- If no session is active, prompts for snapshot/session name to save as.
vim.keymap.set("n", "<leader>Ss", function() require("finni.session").save() end, { desc = "[S]ession [S]ave" })
-- Detach active session and reset all buffers/windows/tabs associated with it.
vim.keymap.set("n", "<leader>Sc", function() require("finni.session").detach(nil, nil, {reset = true}) end, { desc = "[S]ession [C]lose" })
-- Delete a session. Displays an interactive selection.
vim.keymap.set("n", "<leader>SD", function() require("finni.session").delete() end, { desc = "[S]ession [D]elete" })

Ex command

Finni creates an Ex command with the same name (:Finni). It currently exposes the autosession API only.

Make the first argument the name of the Lua function to execute:
```
:Finni reset
```
Follow with positional arguments (nil, false, true are parsed):
```
:Finni load /home/me/code/my_project
```
Pass opts table keys as keyword arguments (by name):
```
:Finni detach save=false reset=true
```

Full example:

:Finni load /home/me/code/my_project modified=false

Pickers

Finni comes with inbuilt support for most popular pickers (snacks.picker, fzf-lua, mini.pick, telescope.nvim). You can load and manage manual sessions, autosessions and projects.

Pickers other than snacks.picker (where no such thing exists) and telescope (which is always available) are registered when their module is required and the underlying picker has already been setup, when you explicitly launch a picker (require ("finni.pickers.mini_pick").manual_picker()) or call the picker's setup function with register being set to true. This means you can call them with the underlying plugin's Ex command afterwards:

:Telescope finni auto_all (telescope.nvim)
:Pick finni_auto_all (mini.pick)
:FzfLua finni_auto_all (fzf-lua)

The pickers are called:

manual: Pick manual sessions.
auto_all: Pick all autosessions from all projects.
auto: Pick autosessions from current project.
projects: Pick known projects.

Keybinds

Select a session and hit enter to load it. Delete a session or project by pressing <M-d> (Alt/Option + d) when selected. From the overview of project autosessions, you can navigate to the projects overview by pressing <C-^> (<C-6>).

Configuration

When launching a picker, you can override any options that get passed to the underlying plugin via the raw key. There are some Finni-specific options (such as dir) as well. If you want to override the defaults without specifying them in every picker call, you can pass them to the picker's setup function (Telescope can handle this automatically for you).

`finni.pickers.PickerConfig` (Class)

Fields:

raw finni.pickers.PickerRawOverrides
Override any options that are passed to a picker. Valid values depend on the specific picker plugin.

Table fields:
- default table
  Override any (picker plugin-specific) options passed to all picker types.
- manual table
  Override any (picker plugin-specific) options passed to the manual session picker.
- auto table
  Override any (picker plugin-specific) options passed to the autosession picker.
- auto_all table
  Override any (picker plugin-specific) options passed to the global autosession picker.
- project table
  Override any (picker plugin-specific) options passed to the project autosession picker.
dir? string
Override the default manual session directory (session.dir)

`snacks.picker`

-- Pick manual sessions
require("finni.pickers.snacks").manual_picker()
-- Pick autosessions, spanning all known projects
require("finni.pickers.snacks").auto_all_picker()
-- Pick autosessions in the active project
require("finni.pickers.snacks").auto_picker()
-- Pick known projects
require("finni.pickers.snacks").project_picker()

`finni.pickers.snacks` (Module)

setup(`opts`)

Override picker defaults

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Defaults for future calls.

manual_picker(`opts`)

Load or delete existing manual sessions.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.

auto_all_picker(`opts`)

Load or delete existing autosessions spanning all projects.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.

auto_picker(`opts`, `project_name`)

Load or delete existing autosessions in specific project only.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.
project_name? string
List autosessions from this project. Defaults to current one.

project_picker(`opts`)

Inspect or delete existing projects. Select project to manage/load its autosessions.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.

`fzf-lua`

-- Pick manual sessions
require("finni.pickers.fzf_lua").manual_picker()
-- Pick autosessions, spanning all known projects
require("finni.pickers.fzf_lua").auto_all_picker()
-- Pick autosessions in the active project
require("finni.pickers.fzf_lua").auto_picker()
-- Pick known projects
require("finni.pickers.fzf_lua").project_picker()

`finni.pickers.fzf_lua` (Module)

setup(`opts`, `register`)

Override picker defaults and register extensions.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Defaults for future calls.
register? boolean
Force registering extensions to be able to launch pickers via the FzfLua Ex command. Note: Loads fzf-lua.

manual_picker(`opts`)

Load or delete existing manual sessions.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.

auto_all_picker(`opts`)

Load or delete existing autosessions spanning all projects.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.

auto_picker(`opts`, `project_name`)

Load or delete existing autosessions in specific project only.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.
project_name? string
List autosessions from this project. Defaults to current one.

project_picker(`opts`)

Inspect or delete existing projects. Select project to manage/load its autosessions.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.

`mini.pick`

-- Pick manual sessions
require("finni.pickers.mini_pick").manual_picker()
-- Pick autosessions, spanning all known projects
require("finni.pickers.mini_pick").auto_all_picker()
-- Pick autosessions in the active project
require("finni.pickers.mini_pick").auto_picker()
-- Pick known projects
require("finni.pickers.mini_pick").project_picker()

`finni.pickers.mini_pick` (Module)

setup(`opts`, `register`)

Override picker defaults and register extensions.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Defaults for future calls.
register? boolean
Force registering extensions to be able to launch pickers via the Pick Ex command. Note: Loads mini.pick.

manual_picker(`opts`)

Load or delete existing manual sessions.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.

auto_all_picker(`opts`)

Load or delete existing autosessions spanning all projects.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.

auto_picker(`opts`, `project_name`)

Load or delete existing autosessions in specific project only.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.
project_name? string
List autosessions from this project. Defaults to current one.

project_picker(`opts`)

Inspect or delete existing projects. Select project to manage/load its autosessions.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.

`telescope.nvim`

-- Pick manual sessions
require("finni.pickers.telescope").manual_picker()
-- Pick autosessions, spanning all known projects
require("finni.pickers.telescope").auto_all_picker()
-- Pick autosessions in the active project
require("finni.pickers.telescope").auto_picker()
-- Pick known projects
require("finni.pickers.telescope").project_picker()

Note: You can explicitly register the finni extension in Telescope's options:

require("telescope").setup({
  -- ...
  extensions = {
    -- ...
    finni = { --[[ custom overrides, see finni.pickers.PickerConfig]] }
  }
})

`finni.pickers.telescope` (Module)

setup(`opts`)

Override picker defaults

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Defaults for future calls.

manual_picker(`opts`)

Load or delete existing manual sessions.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.

auto_all_picker(`opts`)

Load or delete existing autosessions spanning all projects.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.

auto_picker(`opts`, `project_name`)

Load or delete existing autosessions in specific project only.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.
project_name? string
List autosessions from this project. Defaults to current one.

project_picker(`opts`)

Inspect or delete existing projects. Select project to manage/load its autosessions.

Parameters:

opts? Partial<finni.pickers.PickerConfig>
Override Finni-specific and picker-specific options.

👤 Concepts

A project is a container for one or more related sessions that can share some data. It's only relevant for autosessions currently.
A snapshot is the save data required to restore a specific Neovim state. It consists of a JSON data file and optional related files (ShaDa, unwritten buffer contents, undo histories for unwritten buffers).
A session is the relation between current Neovim state and an on-disk snapshot.
An autosession is a session that is derived from an environment. It's restored and attached automatically when triggered. Mixing manual and autosession usage is discouraged currently. Interplay is TBD.
A global session persists everything into its snapshot. Autosessions are always global sessions currently.
A tab-scoped session does not include global state. It only persists windows in its associated tab. By default, persisted buffers are still the same as in global sessions.
Restoring a snapshot loads the saved state into the Neovim instance. If it's a dirty instance, restoration can either reset Neovim's state to a clean one or merge it with the snapshot. By default, restoring a global snapshot resets everything in your Neovim instance, while tab snapshots are restored into a fresh tab. It's possible to restore snapshots without attaching the session after.
Attaching a session means (auto)save operations overwrite the snapshot it points to, using the configuration that was derived when attaching it. There can only be one attached (active) global session, but several tab sessions at a time. Mixing both types is discouraged currently. Interplay is TBD.
Detaching a session means save operations no longer overwrite the snapshot it points to. It can optionally be combined with closing associated buffers/windows/tabs (see reset below).
A reset during session detaching implies only session-associated resources (those persisted to its snapshot) are closed.
A reset during snapshot restoration implies all Neovim resources are closed (buffers, windows, tabs).
Hint: Loading a global session implies potentially detaching an active session, followed by snapshot restoration.
Autosaving means that an attached session is saved automatically at specific points in Neovim's lifetime:
- before the session is detached
- when Neovim is closed
- in regular intervals

❗ Limitations and caveats

Although the snapshot logic is relatively proven, many aspects of how autosessions work, more "exotic" persistency types and their config have not been designed on a drafting board. The sole user has been me, while at the same time developing Finni over the last year. Expect surprises and some clunkiness, for now, but feel free to create an issue if that happens to you. I want this plugin to be useful to many people.
A similar caveat applies to the interplay between different kinds of sessions, which is explicitly to be determined. The safest bet are global sessions, but stick to either manual OR automatic ones.
Don't rely on preservation of modified buffers for highly valuable or otherwise significant work, or if you do, don't curse me when you lose it. With that said, it has been quite reliable during my usage.

⚙️ Configuration

Defaults

{
  autosession = {
    config = {
      modified = false,
    },
    dir = "finni",
    spec = render_autosession_context,
    workspace = util.git.find_workspace_root,
    project_name = util.auto.workspace_project_map,
    session_name = util.auto.generate_name,
    enabled = function(meta)
      return true
    end,
    load_opts = function(meta)
      return {}
    end,
  },
  extensions = {
    quickfix = {},
  },
  load = {
    detail = true,
    order = "modification_time",
  },
  log = {
    level = "warn",
    format = "[%(level)s %(dtime)s] %(message)s%(src_sep)s[%(src_path)s:%(src_line)s]",
    notify_level = "warn",
    notify_format = "%(message)s",
    notify_opts = { title = "Finni" },
    time_format = "%Y-%m-%d %H:%M:%S",
  },
  session = {
    dir = "session",
    options = {
      "binary",
      "bufhidden",
      "buflisted",
      "cmdheight",
      "diff",
      "filetype",
      "modifiable",
      "previewwindow",
      "readonly",
      "scrollbind",
      "winfixheight",
      "winfixwidth",
    },
    buf_filter = default_buf_filter,
    tab_buf_filter = function(tabpage, bufnr, opts)
      return true
    end,
    modified = "auto",
    autosave_enabled = false,
    autosave_interval = 60,
    autosave_notify = true,
    command_history = "auto",
    search_history = "auto",
    input_history = "auto",
    expr_history = "auto",
    debug_history = "auto",
    jumps = "auto",
    changelist = "auto",
    global_marks = "auto",
    local_marks = "auto",
  },
}

`autosession`

Type: finni.UserConfig.autosession?

Influence autosession behavior and contents. Specify defaults that apply to all autosessions. By overriding specific hooks, you can minutely customize almost any aspect of when an autosession is triggered, how it's handled and what is persisted in it.

Table fields

config? finni.core.Session.InitOpts
Save/load configuration for autosessions. Definitions in here override the defaults in session.

Table fields:
- autosave_enabled? boolean
  When this session is attached, automatically save it in intervals. Defaults to false.
- autosave_interval? integer
  Seconds between autosaves of this session, if enabled. Defaults to 60.
- autosave_notify? boolean
  Trigger a notification when autosaving this session. Defaults to true.
- on_attach? finni.core.Session.AttachHook
  A function that's called when attaching to this session. No global default.
- on_detach? finni.core.Session.DetachHook
  A function that's called when detaching from this session. No global default.
- options? string[]
  Save and restore these Neovim (global|buffer|tab|window) options.
- buf_filter? finni.BufFilter
  Function that decides whether a buffer should be included in a snapshot.
- tab_buf_filter? finni.TabBufFilter
  Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
- modified? (boolean|"auto")
  Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
- jumps? boolean
  Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
- changelist? boolean
  Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).
  
  Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
- global_marks? boolean
  Save/load global marks (A-Z, not 0-9 currently).
  
  Only in global sessions.
- local_marks? boolean
  Save/load buffer-specific (local) marks.
  
  Note: Enable this if you track the changelist.
- search_history? (integer|boolean)
  Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- command_history? (integer|boolean)
  Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- input_history? (integer|boolean)
  Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- expr_history? boolean
  Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- debug_history? boolean
  Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
dir? string
Name of the directory to store autosession projects in. Interpreted relative to $XDG_STATE_HOME/$NVIM_APPNAME. Defaults to finni.
spec? finni.auto.SpecHook
This function implements the logic that derives the autosession spec from a path, usually the current working directory. If it returns an autosession spec, Finni automatically switches to the session's workspace root and tries to restore an existing matching session (matched by project name + session name). If it returns nothing, it's interpreted as "no autosession should be active".

It is called during various points in Finni's lifecycle:
1. Neovim startup (if startup autosessions are enabled)
2. When Neovim changes its global working directory
3. When a git branch is switched (if you have installed gitsigns.nvim)
If the return value does not match the current state, the currently active session (if any) is saved + closed and the new session (if any) restored.

The default implementation calls workspace, project_name, session_name, enabled and load_opts to piece together the specification. By overriding this config field, you can implement a custom logic. Mind that the other hooks have no effect then (unless you call them manually).
workspace? finni.auto.WorkspaceHook
Receive the effective nvim cwd, return workspace root and whether it is git-tracked.
project_name? finni.auto.ProjectNameHook
Receive the workspace root dir and whether it's git-tracked, return the project-specific session directory name.
session_name? finni.auto.SessionNameHook
Receive the effective nvim cwd, the workspace root, the project name and workspace repo git info and generate a session name.
enabled? finni.auto.EnabledHook
Receive the effective nvim cwd, the workspace root and project name and decide whether an autosession with this configuration should be active.
load_opts? finni.auto.LoadOptsHook
Influence how an autosession is loaded/persisted, e.g. load the session without attaching it or disable modified persistence. Merged on top of the default autosession configuration for this specific autosession only.

`extensions`

Type: table<string,any>?

Configuration for extensions, both Resession ones and those specific to Finni. Note: Finni first tries to load specified extensions in finni.extensions, but falls back to resession.extension with a warning. Avoid this overhead for Resession extensions by specifying resession_compat = true in the extension config.

`load`

Type: finni.UserConfig.load?

Configure session list information detail and sort order.

Table fields

detail? boolean
Show more detail about the sessions when selecting one to load. Disable if it causes lag.
order? ("modification_time"|"creation_time"|"filename")
Session list order

`log`

Type: finni.UserConfig.log?

Configure plugin logging.

Table fields

level? ("trace"|"debug"|"info"|"warn"|"error"|"off")
Minimum level to log at. Defaults to warn.
notify_level? ("trace"|"debug"|"info"|"warn"|"error"|"off")
Minimum level to use vim.notify for. Defaults to warn.
notify_opts? table
Options to pass to vim.notify. Defaults to { title = "Finni" }
format? string
Log line format string. Note that this works like Python's f-strings. Defaults to [%(level)s %(dtime)s] %(message)s%(src_sep)s[%(src_path)s:%(src_line)s]. Available parameters:
- level Uppercase level name
- message Log message
- dtime Formatted date/time string
- hrtime Time in [ns] without absolute anchor
- src_path Path to the file that called the log function
- src_line Line in src_path that called the log function
- src_sep Whitespace between log line and source of call, 2 tabs for single line, newline + tab for multiline log messages
notify_format? string
Same as format, but for vim.notify message display. Defaults to %(message)s.
time_format? string
strftime format string used for rendering time of call. Defaults to %Y-%m-%d %H:%M:%S
handler? fun(line: finni.log.Line)

`session`

Type: finni.UserConfig.session?

Configure default session behavior and contents, affects both manual and autosessions. Note: In the following field descriptions, "this session" refers to all sessions that don't override these defaults.

Table fields

autosave_enabled? boolean
When this session is attached, automatically save it in intervals. Defaults to false.
autosave_interval? integer
Seconds between autosaves of this session, if enabled. Defaults to 60.
autosave_notify? boolean
Trigger a notification when autosaving this session. Defaults to true.
on_attach? finni.core.Session.AttachHook
A function that's called when attaching to this session. No global default.
on_detach? finni.core.Session.DetachHook
A function that's called when detaching from this session. No global default.
options? string[]
Save and restore these Neovim (global|buffer|tab|window) options.
buf_filter? finni.BufFilter
Function that decides whether a buffer should be included in a snapshot.
tab_buf_filter? finni.TabBufFilter
Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
modified? (boolean|"auto")
Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
jumps? boolean
Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
changelist? boolean
Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).

Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
global_marks? boolean
Save/load global marks (A-Z, not 0-9 currently).

Only in global sessions.
local_marks? boolean
Save/load buffer-specific (local) marks.

Note: Enable this if you track the changelist.
search_history? (integer|boolean)
Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
command_history? (integer|boolean)
Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
input_history? (integer|boolean)
Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
expr_history? boolean
Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
debug_history? boolean
Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
dir? string
Name of the directory to store regular sessions in. Interpreted relative to $XDG_STATE_HOME/$NVIM_APPNAME.

📒 Recipes

Tab-scoped Sessions

When saving a session, only save the current tab

-- Bind `save_tab` instead of `save`
local session = require("finni.session")

vim.keymap.set("n", "<leader>ss", session.save_tab)
vim.keymap.set("n", "<leader>sl", session.load)
vim.keymap.set("n", "<leader>sd", session.delete)

This only saves the current tabpage layout, but 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 only saves buffers in the current tabpage directory:

vim.g.finni_config = {
  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,
}

Custom Extension

You can save custom session data with your own extension.

To create one, add a file to your runtimepath at lua/finni/extensions/<myplugin>.lua. Add the following contents:

local M = {}

--- Called when saving a session. Should return necessary state.
---@param opts (resession.Extension.OnSaveOpts & finni.core.snapshot.Context)
---@param buflist finni.core.snapshot.BufList
---@return any
M.on_save = function(opts, buflist)
  return {}
end

--- Called before restoring anything, receives the data returned by `on_save`.
---@param data any Data returned by `on_save`
---@param opts finni.core.snapshot.Context
---@param buflist string[]
M.on_pre_load = function(data)
  -- This is run before the buffers, windows, and tabs are restored
end

--- Called after restoring everything, receives the data returned by `on_save`.
---@param data any Data returned by `on_save`
---@param opts finni.core.snapshot.Context
---@param buflist string[]
M.on_post_load = function(data)
  -- This is run after the buffers, windows, and tabs are restored
end

--- Called when Finni gets configured.
--- This function is optional.
---@param data table Configuration data passed in the config (in `extensions.<extension_name>`)
M.config = function(data)
  -- Optional setup for your extension
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 false
end

--- Save data for a window. Called when `is_win_supported` returned true.
--- Note: Finni does not focus tabs or windows during session save,
---       so the current window/buffer will most likely be a different one than `winid`.
---@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 after creating a tab's windows with the data from `save_win`.
---@param winid integer
---@param data any
---@param win finni.core.layout.WinInfo
---@return integer? new_winid If the original window has been replaced, return the new ID that should replace it
M.load_win = function(winid, config, win)
  -- Restore the window from the config
end

return M

Enable your extension by adding a corresponding key in the extensions option:

vim.g.finni_config = {
  extensions = {
    myplugin = {
      -- This table is passed to M.config(). It can be empty.
    },
  },
}

For tab-scoped sessions, the on_save and on_load methods of extensions are disabled by default. You can force-enable them by setting the enable_in_tab option to true (it's an inbuilt option respected for all extensions).

vim.g.finni_config = {
  -- ...
  extensions = {
    myplugin = {
      enable_in_tab = true,
    },
  }
}

🔌 API

`finni.session` (Module)

Interactive API, (mostly) compatible with stevearc/resession.nvim.

save(`name`, `opts`)

Save the current global state to disk

Parameters:

name? string
Name of the global session to save. If not provided, takes name of attached one or prompts user.
opts? (finni.session.SaveOpts&finni.core.PassthroughOpts)

Table fields:
- dir? string
  Name of session directory (overrides config.dir)
- autosave_enabled? boolean
  When this session is attached, automatically save it in intervals. Defaults to false.
- autosave_interval? integer
  Seconds between autosaves of this session, if enabled. Defaults to 60.
- autosave_notify? boolean
  Trigger a notification when autosaving this session. Defaults to true.
- on_attach? finni.core.Session.AttachHook
  A function that's called when attaching to this session. No global default.
- on_detach? finni.core.Session.DetachHook
  A function that's called when detaching from this session. No global default.
- options? string[]
  Save and restore these Neovim (global|buffer|tab|window) options.
- buf_filter? finni.BufFilter
  Function that decides whether a buffer should be included in a snapshot.
- tab_buf_filter? finni.TabBufFilter
  Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
- modified? (boolean|"auto")
  Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
- jumps? boolean
  Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
- changelist? boolean
  Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).
  
  Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
- global_marks? boolean
  Save/load global marks (A-Z, not 0-9 currently).
  
  Only in global sessions.
- local_marks? boolean
  Save/load buffer-specific (local) marks.
  
  Note: Enable this if you track the changelist.
- search_history? (integer|boolean)
  Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- command_history? (integer|boolean)
  Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- input_history? (integer|boolean)
  Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- expr_history? boolean
  Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- debug_history? boolean
  Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- meta? table
  External data remembered in association with this session. Useful to build on top of the core API.
- attach? boolean
  Attach to/stay attached to session after operation
- notify? boolean
  Notify on success
- reset? boolean
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.

save_tab(`name`, `opts`)

Save the state of the current tabpage to disk

Parameters:

name? string
Name of the tabpage session to save. If not provided, takes name of attached one in current tabpage or prompts user.
opts? (finni.session.SaveOpts&finni.core.PassthroughOpts)

Table fields:
- dir? string
  Name of session directory (overrides config.dir)
- autosave_enabled? boolean
  When this session is attached, automatically save it in intervals. Defaults to false.
- autosave_interval? integer
  Seconds between autosaves of this session, if enabled. Defaults to 60.
- autosave_notify? boolean
  Trigger a notification when autosaving this session. Defaults to true.
- on_attach? finni.core.Session.AttachHook
  A function that's called when attaching to this session. No global default.
- on_detach? finni.core.Session.DetachHook
  A function that's called when detaching from this session. No global default.
- options? string[]
  Save and restore these Neovim (global|buffer|tab|window) options.
- buf_filter? finni.BufFilter
  Function that decides whether a buffer should be included in a snapshot.
- tab_buf_filter? finni.TabBufFilter
  Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
- modified? (boolean|"auto")
  Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
- jumps? boolean
  Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
- changelist? boolean
  Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).
  
  Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
- global_marks? boolean
  Save/load global marks (A-Z, not 0-9 currently).
  
  Only in global sessions.
- local_marks? boolean
  Save/load buffer-specific (local) marks.
  
  Note: Enable this if you track the changelist.
- search_history? (integer|boolean)
  Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- command_history? (integer|boolean)
  Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- input_history? (integer|boolean)
  Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- expr_history? boolean
  Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- debug_history? boolean
  Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- meta? table
  External data remembered in association with this session. Useful to build on top of the core API.
- attach? boolean
  Attach to/stay attached to session after operation
- notify? boolean
  Notify on success
- reset? boolean
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.

save_all(`opts`)

Save all currently attached sessions to disk

Parameters:

opts? (finni.SideEffects.Notify&finni.core.PassthroughOpts)

Table fields:
- notify? boolean
  Notify on success

load(`name`, `opts`)

Load a session from disk.

Note: The default value of opts.reset = "auto" resets when loading a normal session, but not when loading a tab-scoped session.

Parameters:

name? string
Name of the session to load from session dir. If not provided, prompts user.
opts? (finni.session.LoadOpts&finni.core.PassthroughOpts)

Table fields:
- dir? string
  Name of session directory (overrides config.dir)
- autosave_enabled? boolean
  When this session is attached, automatically save it in intervals. Defaults to false.
- autosave_interval? integer
  Seconds between autosaves of this session, if enabled. Defaults to 60.
- autosave_notify? boolean
  Trigger a notification when autosaving this session. Defaults to true.
- on_attach? finni.core.Session.AttachHook
  A function that's called when attaching to this session. No global default.
- on_detach? finni.core.Session.DetachHook
  A function that's called when detaching from this session. No global default.
- options? string[]
  Save and restore these Neovim (global|buffer|tab|window) options.
- buf_filter? finni.BufFilter
  Function that decides whether a buffer should be included in a snapshot.
- tab_buf_filter? finni.TabBufFilter
  Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
- modified? (boolean|"auto")
  Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
- jumps? boolean
  Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
- changelist? boolean
  Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).
  
  Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
- global_marks? boolean
  Save/load global marks (A-Z, not 0-9 currently).
  
  Only in global sessions.
- local_marks? boolean
  Save/load buffer-specific (local) marks.
  
  Note: Enable this if you track the changelist.
- search_history? (integer|boolean)
  Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- command_history? (integer|boolean)
  Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- input_history? (integer|boolean)
  Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- expr_history? boolean
  Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- debug_history? boolean
  Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- meta? table
  External data remembered in association with this session. Useful to build on top of the core API.
- attach? boolean
  Attach to/stay attached to session after operation
- reset? (boolean|"auto")
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot. auto resets only for global sessions.
- save? boolean
  Save/override autosave config for affected sessions before the operation
- silence_errors? boolean
  Don't error during this operation

detach(`target`, `reason`, `opts`)

Detach from the session that contains the target (or all active sessions if unspecified).

Parameters:

target? ("__global"|"__active"|"__active_tab"|"__all_tabs"|string|integer...)
The scope/session name/tabid to detach from. If unspecified, detaches all sessions.
reason? (finni.core.Session.DetachReasonBuiltin|string)
Pass a custom reason to detach handlers. Defaults to request.
opts? (finni.core.Session.DetachOpts&finni.core.PassthroughOpts)

Table fields:
- reset? boolean
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.
- save? boolean
  Save/override autosave config for affected sessions before the operation

Returns: detached boolean
Whether we detached from any session

list(`opts`)

List all available saved sessions in session dir

Parameters:

opts? finni.session.DirParam

Table fields:
- dir? string
  Name of session directory (overrides config.dir)

Returns: sessions_in_dir string[]

delete(`name`, `opts`)

Delete a saved session from session dir

Parameters:

name? string
Name of the session. If not provided, prompts user
opts? (finni.session.DeleteOpts&finni.core.PassthroughOpts)

Table fields:
- dir? string
  Name of session directory (overrides config.dir)
- notify? boolean
  Notify on success
- reset? boolean
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.
- silence_errors? boolean
  Don't error during this operation

`finni.auto` (Module)

explicit_ctx(`session`, `project`, `opts`)

Get the autosession configuration for an explicit project/session name pair. Note: Can fail if a directory can map to multiple sessions (e.g. with Git branches) and its current state does not correspond to the session.

Parameters:

session string
Name of the session
project? string
Name of the project. If unspecified, defaults to current one
opts? finni.SideEffects.SilenceErrors

Table fields:
- silence_errors? boolean
  Don't error during this operation

Returns: finni.auto.AutosessionContext?

save(`opts`)

Save the currently active autosession.

Parameters:

opts? (finni.auto.SaveOpts&finni.core.PassthroughOpts)

Table fields:
- attach? boolean
  Attach to/stay attached to session after operation
- notify? boolean
  Notify on success
- reset? boolean
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.

detach(`opts`)

Detach from the currently active autosession. If autosave is enabled, save it. Optionally close everything.

Parameters:

opts? (finni.core.Session.DetachOpts&finni.core.PassthroughOpts)

Table fields:
- reset? boolean
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.
- save? boolean
  Save/override autosave config for affected sessions before the operation

load(`autosession`, `opts`)

Load an autosession.

Parameters:

autosession? (finni.auto.AutosessionContext|string)
The autosession table as rendered by get_ctx or cwd to pass to it
opts? finni.auto.LoadOpts

Table fields:
- autosave_enabled? boolean
  When this session is attached, automatically save it in intervals. Defaults to false.
- autosave_interval? integer
  Seconds between autosaves of this session, if enabled. Defaults to 60.
- autosave_notify? boolean
  Trigger a notification when autosaving this session. Defaults to true.
- on_attach? finni.core.Session.AttachHook
  A function that's called when attaching to this session. No global default.
- on_detach? finni.core.Session.DetachHook
  A function that's called when detaching from this session. No global default.
- options? string[]
  Save and restore these Neovim (global|buffer|tab|window) options.
- buf_filter? finni.BufFilter
  Function that decides whether a buffer should be included in a snapshot.
- tab_buf_filter? finni.TabBufFilter
  Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
- modified? (boolean|"auto")
  Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
- jumps? boolean
  Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
- changelist? boolean
  Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).
  
  Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
- global_marks? boolean
  Save/load global marks (A-Z, not 0-9 currently).
  
  Only in global sessions.
- local_marks? boolean
  Save/load buffer-specific (local) marks.
  
  Note: Enable this if you track the changelist.
- search_history? (integer|boolean)
  Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- command_history? (integer|boolean)
  Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- input_history? (integer|boolean)
  Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- expr_history? boolean
  Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- debug_history? boolean
  Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- meta? table
  External data remembered in association with this session. Useful to build on top of the core API.
- attach? boolean
  Attach to/stay attached to session after operation
- save? boolean
  Save/override autosave config for affected sessions before the operation
- reset? (boolean|"auto")
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot. auto resets only for global sessions.
- silence_errors? boolean
  Don't error during this operation

switch(`session`, `project`, `opts`)

Load an existing autosession by project name and session name. Note: This can fail, e.g. when an autosession is associated with a git branch and the worktree has checked out a different one.

Parameters:

session string
Name of the session to load
project? string
Name of the project. If unspecified, defaults to current one
opts? finni.auto.LoadOpts

Table fields:
- autosave_enabled? boolean
  When this session is attached, automatically save it in intervals. Defaults to false.
- autosave_interval? integer
  Seconds between autosaves of this session, if enabled. Defaults to 60.
- autosave_notify? boolean
  Trigger a notification when autosaving this session. Defaults to true.
- on_attach? finni.core.Session.AttachHook
  A function that's called when attaching to this session. No global default.
- on_detach? finni.core.Session.DetachHook
  A function that's called when detaching from this session. No global default.
- options? string[]
  Save and restore these Neovim (global|buffer|tab|window) options.
- buf_filter? finni.BufFilter
  Function that decides whether a buffer should be included in a snapshot.
- tab_buf_filter? finni.TabBufFilter
  Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
- modified? (boolean|"auto")
  Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
- jumps? boolean
  Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
- changelist? boolean
  Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).
  
  Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
- global_marks? boolean
  Save/load global marks (A-Z, not 0-9 currently).
  
  Only in global sessions.
- local_marks? boolean
  Save/load buffer-specific (local) marks.
  
  Note: Enable this if you track the changelist.
- search_history? (integer|boolean)
  Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- command_history? (integer|boolean)
  Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- input_history? (integer|boolean)
  Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- expr_history? boolean
  Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- debug_history? boolean
  Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- meta? table
  External data remembered in association with this session. Useful to build on top of the core API.
- attach? boolean
  Attach to/stay attached to session after operation
- save? boolean
  Save/override autosave config for affected sessions before the operation
- reset? (boolean|"auto")
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot. auto resets only for global sessions.
- silence_errors? boolean
  Don't error during this operation

reload()

If an autosession is active, save it and detach. Then try to start a new one.

start(`cwd`, `opts`)

Start Finni:

If the current working directory has an associated project and session, closes everything and loads that session.
In any case, start monitoring for directory or branch changes.

Parameters:

cwd? string
Working directory to switch to before starting autosession. Defaults to nvim's process' cwd.
opts? finni.auto.LoadOpts

Table fields:
- autosave_enabled? boolean
  When this session is attached, automatically save it in intervals. Defaults to false.
- autosave_interval? integer
  Seconds between autosaves of this session, if enabled. Defaults to 60.
- autosave_notify? boolean
  Trigger a notification when autosaving this session. Defaults to true.
- on_attach? finni.core.Session.AttachHook
  A function that's called when attaching to this session. No global default.
- on_detach? finni.core.Session.DetachHook
  A function that's called when detaching from this session. No global default.
- options? string[]
  Save and restore these Neovim (global|buffer|tab|window) options.
- buf_filter? finni.BufFilter
  Function that decides whether a buffer should be included in a snapshot.
- tab_buf_filter? finni.TabBufFilter
  Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
- modified? (boolean|"auto")
  Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
- jumps? boolean
  Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
- changelist? boolean
  Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).
  
  Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
- global_marks? boolean
  Save/load global marks (A-Z, not 0-9 currently).
  
  Only in global sessions.
- local_marks? boolean
  Save/load buffer-specific (local) marks.
  
  Note: Enable this if you track the changelist.
- search_history? (integer|boolean)
  Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- command_history? (integer|boolean)
  Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- input_history? (integer|boolean)
  Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- expr_history? boolean
  Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- debug_history? boolean
  Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- meta? table
  External data remembered in association with this session. Useful to build on top of the core API.
- attach? boolean
  Attach to/stay attached to session after operation
- save? boolean
  Save/override autosave config for affected sessions before the operation
- reset? (boolean|"auto")
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot. auto resets only for global sessions.
- silence_errors? boolean
  Don't error during this operation

stop()

Stop Finni:

If we're inside an active autosession, save it and detach. Keep buffers/windows/tabs etc. by default.
In any case, stop monitoring for directory or branch changes.

delete(`session`, `project`, `opts`)

Delete a specific autosession.

Parameters:

session string
Session to delete
project? string
Project name of session to delete. If unspecified, defaults to current one.
opts? (finni.SideEffects.Notify&finni.SideEffects.SilenceErrors)

Table fields:
- notify? boolean
  Notify on success
- silence_errors? boolean
  Don't error during this operation

reset(`opts`)

Delete the currently active autosession. Close everything. Attempt to start a new autosession (optionally).

Parameters:

opts? finni.auto.ResetOpts

Table fields:
- silence_errors? boolean
  Don't error during this operation
- reset? boolean
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.
- notify? boolean
  Notify on success
- cwd? (string|true)
  Path to a directory associated with the session to reset instead of current one. Set this to true to use nvim's current global CWD.
- reload? boolean
  Attempt to restart a new autosession after reset. Defaults to true.

current_project()

Get the name of the currently active project.

Returns: string?

reset_project(`opts`)

Remove all autosessions associated with a project. If the target is the active project, reset current session as well and close everything.

Parameters:

opts? finni.auto.ResetProjectOpts

Table fields:
- notify? boolean
  Notify on success
- name? string
  Specify the project to reset. If unspecified, resets active project, if available.
- force? boolean
  Force recursive deletion of project dir outside of configured root

list(`opts`)

List autosessions associated with a project.

Parameters:

opts? finni.auto.ListOpts
Specify the project to list. If unspecified, lists active project, if available.

Table fields:
- cwd? string
  Path to a directory associated with the project to list
- project_dir? string
  Path to the project session dir
- project_name? string
  Name of the project

Returns: session_names string[]
List of known sessions associated with project

list_projects(`opts`)

List all known projects.

Overloads:

fun() -> string[]
fun(opts: { with_sessions: true }) -> table<string,string[]>

Parameters:

opts? finni.auto.ListProjectOpts

Table fields:
- with_sessions? boolean
  Additionally list all known sessions for each listed project. Defaults to false.

Returns: (string[]|table<string,string[]>)

migrate_projects(`opts`)

Dev helper currently (beware: unstable/inefficient). When changing the mapping from workspace to project name, all previously saved states would be lost. This tries to migrate state data to the new mapping, cleans projects whose cwd does not exist anymore or which are disabled Caution! This does not account for projects with multiple associated directories/sessions! Checks the first session's cwd/enabled state only!

Parameters:

opts? finni.auto.MigrateProjectsOpts
Options for migration. You need to pass {dry_run = false} for this function to have an effect.

Table fields:
- dry_run? boolean
  Don't execute the migration, only show what would have happened. Defaults to true, meaning you need to explicitly set this to false to have an effect.
- old_root? string
  If the value of autosession.dir has changed, the old value. Defaults to autosession.dir.

Returns: migration_result table<("broken"|"missing"|"skipped"|"migrated"...),table[]>

info(`opts`)

Return information about the currently active session. Includes autosession information, if it is an autosession.

Parameters:

opts? { with_snapshot: boolean? }

Table fields:
- with_snapshot? boolean

Returns: active_info? finni.auto.ActiveAutosessionInfo
Information about the active session, even if not an autosession. Always includes snapshot configuration, session meta config and whether it is an autosession. For autosessions, also includes autosession config.

🧩 Extensions

Built-in

quickfix:

Persist all quickfix lists, currently active list, active position in list and quickfix window.
colorscheme:

Persist color scheme.
dap:

Persist nvim-dap breakpoints.
neogit:

Persist Neogit status and commit views.
oil:

Persist Oil windows.

Note: Customized from the one embedded in oil.nvim to correctly restore view.

External

Here are some examples of external extensions:

aerial.nvim:

Note: For Resession, which is compatible with Finni.
overseer.nvim:

Note: For Resession, which is compatible with Finni.

❓ FAQ

Q: Why another session plugin?

A1: All the other plugins (with the exception of resession.nvim) use :mksession under the hood A2: Resession cannot be bent enough via its interface to support everything Finni does. Its API is difficult to build another plugin on top of (e.g. cannot get session table without Resession saving it to a file first).

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 'sessionoptions' covers your use case, then you're golden. If you want anything else, you're out of luck.

Q: Why Finni?

A: One might assume the name of this plugin is a word play on the French "c'est fini" or a contraction of "fin" (French: end) and either "nie" (German: never) or even the "Ni!" by the "Knights Who Say 'Ni!'", for some reason.

But one would be mistaken.

This plugin is dedicated to one of the loveliest creatures that ever walked our Earth, my little kind-hearted and trustful to a fault sweetie Finni. ❤️

You lived a long life (for a hamster...) and were the best boy until the end. I will miss you, your curiosity and your unwavering will dearly, my little Finni.

Like your namesake plugin allows Neovim sessions to, may your memory live on forever.

Type Reference

`finni.auto.ActiveAutosessionInfo` (Class)

Fields:

session_file string
Path to the session file
state_dir string
Path to the directory holding session-associated data
context_dir string
Directory for shared state between all sessions in the same context (dir for manual sessions, project dir for autosessions)
autosave_enabled boolean
When this session is attached, automatically save it in intervals. Defaults to false.
autosave_interval integer
Seconds between autosaves of this session, if enabled. Defaults to 60.
name string
Name of the session
tab_scoped boolean
Whether the session is tab-scoped
is_autosession boolean
Whether this is an autosession or a manual one
autosave_notify? boolean
Trigger a notification when autosaving this session. Defaults to true.
on_attach? finni.core.Session.AttachHook
A function that's called when attaching to this session. No global default.
on_detach? finni.core.Session.DetachHook
A function that's called when detaching from this session. No global default.
meta? table
External data remembered in association with this session. Useful to build on top of the core API.
options? string[]
Save and restore these Neovim (global|buffer|tab|window) options.
buf_filter? finni.BufFilter
Function that decides whether a buffer should be included in a snapshot.
tab_buf_filter? finni.TabBufFilter
Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
modified? (boolean|"auto")
Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
jumps? boolean
Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
changelist? boolean
Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).

Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
global_marks? boolean
Save/load global marks (A-Z, not 0-9 currently).

Only in global sessions.
local_marks? boolean
Save/load buffer-specific (local) marks.

Note: Enable this if you track the changelist.
search_history? (integer|boolean)
Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
command_history? (integer|boolean)
Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
input_history? (integer|boolean)
Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
expr_history? boolean
Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
debug_history? boolean
Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
tabid? (finni.core.TabID|true)
Tab number the session is attached to, if any. Can be true, which indicates it's a tab-scoped session that has not been restored yet - although not when requesting via the API
autosession_config? finni.auto.AutosessionContext
When this is an autosession, the internal configuration that was rendered.

Table fields:
- project finni.auto.AutosessionConfig.ProjectInfo
- root string
  The top level directory for this session (workspace root). Usually equals the project root, but can be different when git worktrees are used.
- name string
  The name of the session
- config finni.auto.LoadOpts
  Session-specific load/autosave options.
- cwd string
  The effective working directory that was determined when loading this auto-session
autosession_data? finni.core.Snapshot
The most recent snapshotted state of this named autosession

Table fields:
- buffers finni.core.Snapshot.BufData[]
  Buffer-specific data like name, buffer options, local marks, changelist
- tabs finni.core.Snapshot.TabData[]
  Tab-specific and window layout data, including tab cwd and window-specific jumplists
- tab_scoped boolean
  Whether this snapshot was derived from a single tab
- global finni.core.Snapshot.GlobalData
  Global snapshot data like process CWD, global options and global marks
- modified? table<finni.core.BufUUID,true?>
  List of buffers (identified by internal UUID) whose unsaved modifications were backed up in the snapshot
- buflist string[]
  List of named buffers that are referenced somewhere in this snapshot. Used to reduce repetition of buffer paths in save file, especially lists of named marks (jumplist, quickfix and location lists).

`finni.auto.AutosessionConfig.ProjectInfo` (Class)

Fields:

data_dir string
The path of the directory that is used to save autosession data related to this project.
name string
The name of the project
repo? finni.auto.AutosessionSpec.GitInfo
When the project is defined as a git repository, meta info

Table fields:
- commongitdir string
  The common git dir, usually equal to gitdir, unless the worktree is not the default workdir (e.g. in worktree checkuots of bare repos). Then it's the actual repo root and gitdir is <git_common_dir>/worktrees/<worktree_name>
- gitdir string
  The repository (or worktree) data path
- toplevel string
  The path of the checked out worktree
- branch? string
  The branch the worktree has checked out
- default_branch? string
  The name of the default branch

`finni.auto.AutosessionContext` (Class)

Fields:

project finni.auto.AutosessionConfig.ProjectInfo

Table fields:
- data_dir string
  The path of the directory that is used to save autosession data related to this project.
- name string
  The name of the project
- repo? finni.auto.AutosessionSpec.GitInfo
  When the project is defined as a git repository, meta info
root string
The top level directory for this session (workspace root). Usually equals the project root, but can be different when git worktrees are used.
name string
The name of the session
config finni.auto.LoadOpts
Session-specific load/autosave options.

Table fields:
- autosave_enabled? boolean
  When this session is attached, automatically save it in intervals. Defaults to false.
- autosave_interval? integer
  Seconds between autosaves of this session, if enabled. Defaults to 60.
- autosave_notify? boolean
  Trigger a notification when autosaving this session. Defaults to true.
- on_attach? finni.core.Session.AttachHook
  A function that's called when attaching to this session. No global default.
- on_detach? finni.core.Session.DetachHook
  A function that's called when detaching from this session. No global default.
- options? string[]
  Save and restore these Neovim (global|buffer|tab|window) options.
- buf_filter? finni.BufFilter
  Function that decides whether a buffer should be included in a snapshot.
- tab_buf_filter? finni.TabBufFilter
  Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
- modified? (boolean|"auto")
  Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
- jumps? boolean
  Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
- changelist? boolean
  Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).
  
  Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
- global_marks? boolean
  Save/load global marks (A-Z, not 0-9 currently).
  
  Only in global sessions.
- local_marks? boolean
  Save/load buffer-specific (local) marks.
  
  Note: Enable this if you track the changelist.
- search_history? (integer|boolean)
  Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- command_history? (integer|boolean)
  Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- input_history? (integer|boolean)
  Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- expr_history? boolean
  Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- debug_history? boolean
  Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- meta? table
  External data remembered in association with this session. Useful to build on top of the core API.
- attach? boolean
  Attach to/stay attached to session after operation
- save? boolean
  Save/override autosave config for affected sessions before the operation
- reset? (boolean|"auto")
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot. auto resets only for global sessions.
- silence_errors? boolean
  Don't error during this operation
cwd string
The effective working directory that was determined when loading this auto-session

`finni.auto.AutosessionSpec.GitInfo` (Class)

Information about a Git repository that is associated with a project.

Fields:

commongitdir string
The common git dir, usually equal to gitdir, unless the worktree is not the default workdir (e.g. in worktree checkuots of bare repos). Then it's the actual repo root and gitdir is <git_common_dir>/worktrees/<worktree_name>
gitdir string
The repository (or worktree) data path
toplevel string
The path of the checked out worktree
branch? string
The branch the worktree has checked out
default_branch? string
The name of the default branch

`finni.auto.EnabledHook` (Alias)

Type: fun(meta: { cwd: string, project_name: string, session_name: string, workspace: string }) -> boolean

Function that decides whether an autosession should be processed further. Receives output of WorkspaceHook, ProjectNameHook and SessionNameHook.

`finni.auto.ListOpts` (Class)

Options for listing autosessions in a project. cwd, project_dir and project_name are different ways of referencing a project and only one of them is respected.

Fields:

cwd? string
Path to a directory associated with the project to list
project_dir? string
Path to the project session dir
project_name? string
Name of the project

`finni.auto.ListProjectOpts` (Class)

Fields:

with_sessions? boolean
Additionally list all known sessions for each listed project. Defaults to false.

`finni.auto.LoadOpts` (Alias)

Type: (finni.core.Session.InitOptsWithMeta&finni.SideEffects.Attach&finni.SideEffects.Save&finni.SideEffects.ResetAuto&finni.SideEffects.SilenceErrors&finni.core.PassthroughOpts)

API options for auto.load

Fields:

autosave_enabled? boolean
When this session is attached, automatically save it in intervals. Defaults to false.
autosave_interval? integer
Seconds between autosaves of this session, if enabled. Defaults to 60.
autosave_notify? boolean
Trigger a notification when autosaving this session. Defaults to true.
on_attach? finni.core.Session.AttachHook
A function that's called when attaching to this session. No global default.
on_detach? finni.core.Session.DetachHook
A function that's called when detaching from this session. No global default.
options? string[]
Save and restore these Neovim (global|buffer|tab|window) options.
buf_filter? finni.BufFilter
Function that decides whether a buffer should be included in a snapshot.
tab_buf_filter? finni.TabBufFilter
Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
modified? (boolean|"auto")
Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
jumps? boolean
Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
changelist? boolean
Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).

Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
global_marks? boolean
Save/load global marks (A-Z, not 0-9 currently).

Only in global sessions.
local_marks? boolean
Save/load buffer-specific (local) marks.

Note: Enable this if you track the changelist.
search_history? (integer|boolean)
Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
command_history? (integer|boolean)
Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
input_history? (integer|boolean)
Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
expr_history? boolean
Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
debug_history? boolean
Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
meta? table
External data remembered in association with this session. Useful to build on top of the core API.
attach? boolean
Attach to/stay attached to session after operation
save? boolean
Save/override autosave config for affected sessions before the operation
reset? (boolean|"auto")
When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot. auto resets only for global sessions.
silence_errors? boolean
Don't error during this operation

`finni.auto.LoadOptsHook` (Alias)

Type: fun(meta: { cwd: string, project_name: string, session_name: string, workspace: string }) -> auto.LoadOpts?

Function that can return autosession-specific load option overrides. Receives output of WorkspaceHook, ProjectNameHook and SessionNameHook.

`finni.auto.MigrateProjectsOpts` (Class)

Fields:

dry_run? boolean
Don't execute the migration, only show what would have happened. Defaults to true, meaning you need to explicitly set this to false to have an effect.
old_root? string
If the value of autosession.dir has changed, the old value. Defaults to autosession.dir.

`finni.auto.ProjectNameHook` (Alias)

Type: fun(workspace: string, git_info: auto.AutosessionSpec.GitInfo?) -> string

Function that derives the project name from output of WorkspaceHook.

`finni.auto.ResetOpts` (Class)

API options for auto.reset

Fields:

silence_errors? boolean
Don't error during this operation
reset? boolean
When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.
notify? boolean
Notify on success
cwd? (string|true)
Path to a directory associated with the session to reset instead of current one. Set this to true to use nvim's current global CWD.
reload? boolean
Attempt to restart a new autosession after reset. Defaults to true.

`finni.auto.ResetProjectOpts` (Class)

Fields:

notify? boolean
Notify on success
name? string
Specify the project to reset. If unspecified, resets active project, if available.
force? boolean
Force recursive deletion of project dir outside of configured root

`finni.auto.SaveOpts` (Alias)

Type: (finni.SideEffects.Attach&finni.SideEffects.Notify&finni.SideEffects.Reset)

API options for auto.save

Fields:

attach? boolean
Attach to/stay attached to session after operation
notify? boolean
Notify on success
reset? boolean
When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.

`finni.auto.SessionNameHook` (Alias)

Type: fun(meta: { cwd: string, git_info: auto.AutosessionSpec.GitInfo?, project_name: string, workspace: string }) -> string

Function that derives the session name from output of WorkspaceHook and ProjectNameHook.

`finni.auto.SpecHook` (Alias)

Type: fun(cwd: string) -> auto.AutosessionSpec?

Function that derives autosession configuration from a path. The default implementation calls into all other autosession hooks that can be overridden in the config.

`finni.auto.WorkspaceHook` (Alias)

Type: fun(cwd: string) -> (string,boolean)

Function that derives workspace root and git-tracked status from a path.

`finni.BufFilter` (Alias)

Type: fun(bufnr: integer, opts: finni.core.snapshot.CreateOpts) -> boolean

Function that decides whether a buffer should be included in a snapshot.

`finni.core.ActiveSession` (Class)

An active (attached) session.

Fields:

session_file string
Path to the session file
state_dir string
Path to the directory holding session-associated data
context_dir string
Directory for shared state between all sessions in the same context (dir for manual sessions, project dir for autosessions)
autosave_enabled boolean
Autosave this attached session in intervals and when detaching
autosave_interval integer
Seconds between autosaves of this session, if enabled.
name string
tab_scoped boolean
autosave_notify? boolean
Trigger a notification when autosaving this session. Defaults to true.
on_attach? finni.core.Session.AttachHook
A function that's called when attaching to this session. No global default.
on_detach? finni.core.Session.DetachHook
A function that's called when detaching from this session. No global default.
meta? table
External data remembered in association with this session. Useful to build on top of the core API.
options? string[]
Save and restore these Neovim (global|buffer|tab|window) options.
buf_filter? finni.BufFilter
Function that decides whether a buffer should be included in a snapshot.
tab_buf_filter? finni.TabBufFilter
Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
modified? (boolean|"auto")
Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
jumps? boolean
Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
changelist? boolean
Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).

Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
global_marks? boolean
Save/load global marks (A-Z, not 0-9 currently).

Only in global sessions.
local_marks? boolean
Save/load buffer-specific (local) marks.

Note: Enable this if you track the changelist.
search_history? (integer|boolean)
Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
command_history? (integer|boolean)
Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
input_history? (integer|boolean)
Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
expr_history? boolean
Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
debug_history? boolean
Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
tabid? finni.core.TabID

new(`name`, `session_file`, `state_dir`, `context_dir`, `opts`, `tabid`, `needs_restore`)

Parameters:

name string
session_file string
state_dir string
context_dir string
opts finni.core.Session.InitOptsWithMeta
tabid true
needs_restore true

Returns: finni.core.PendingSession<finni.core.Session.TabTarget>

from_snapshot(`name`, `session_file`, `state_dir`, `context_dir`, `opts`)

Create a new session by loading a snapshot, which you need to restore explicitly.

Parameters:

name string
session_file string
state_dir string
context_dir string
opts (finni.core.Session.InitOptsWithMeta&finni.SideEffects.SilenceErrors)

Table fields:
- autosave_enabled? boolean
  When this session is attached, automatically save it in intervals. Defaults to false.
- autosave_interval? integer
  Seconds between autosaves of this session, if enabled. Defaults to 60.
- autosave_notify? boolean
  Trigger a notification when autosaving this session. Defaults to true.
- on_attach? finni.core.Session.AttachHook
  A function that's called when attaching to this session. No global default.
- on_detach? finni.core.Session.DetachHook
  A function that's called when detaching from this session. No global default.
- options? string[]
  Save and restore these Neovim (global|buffer|tab|window) options.
- buf_filter? finni.BufFilter
  Function that decides whether a buffer should be included in a snapshot.
- tab_buf_filter? finni.TabBufFilter
  Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
- modified? (boolean|"auto")
  Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
- jumps? boolean
  Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
- changelist? boolean
  Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).
  
  Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
- global_marks? boolean
  Save/load global marks (A-Z, not 0-9 currently).
  
  Only in global sessions.
- local_marks? boolean
  Save/load buffer-specific (local) marks.
  
  Note: Enable this if you track the changelist.
- search_history? (integer|boolean)
  Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- command_history? (integer|boolean)
  Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- input_history? (integer|boolean)
  Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- expr_history? boolean
  Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- debug_history? boolean
  Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- meta? table
  External data remembered in association with this session. Useful to build on top of the core API.
- silence_errors? boolean
  Don't error during this operation

Returns:

loaded_session? finni.core.PendingSession
Session object, if the snapshot could be loaded
snapshot? finni.core.Snapshot
Snapshot data, if it could be loaded

ActiveSession:add_hook(`event`, `hook`)

Parameters:

event "detach"
hook finni.core.Session.DetachHook

Returns: self

ActiveSession:update(`opts`)

Update modifiable options without attaching/detaching a session

Parameters:

opts finni.core.Session.InitOptsWithMeta

Returns: modified boolean
Indicates whether any config modifications occurred

ActiveSession:restore(`opts`, `snapshot`)

Restore a snapshot from disk or memory It seems emmylua does not pick up this override and infers IdleSession instead.

Parameters:

opts? (finni.core.Session.RestoreOpts&finni.core.PassthroughOpts)

Table fields:
- reset? boolean
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.
- silence_errors? boolean
  Don't error during this operation
snapshot? finni.core.Snapshot
Snapshot to restore. If unspecified, loads from file.

Table fields:
- buffers finni.core.Snapshot.BufData[]
  Buffer-specific data like name, buffer options, local marks, changelist
- tabs finni.core.Snapshot.TabData[]
  Tab-specific and window layout data, including tab cwd and window-specific jumplists
- tab_scoped boolean
  Whether this snapshot was derived from a single tab
- global finni.core.Snapshot.GlobalData
  Global snapshot data like process CWD, global options and global marks
- modified? table<finni.core.BufUUID,true?>
  List of buffers (identified by internal UUID) whose unsaved modifications were backed up in the snapshot
- buflist string[]
  List of named buffers that are referenced somewhere in this snapshot. Used to reduce repetition of buffer paths in save file, especially lists of named marks (jumplist, quickfix and location lists).

Returns:

self finni.core.ActiveSession
Same object.
success boolean
Whether restoration was successful. Only sensible when silence_errors is true.

ActiveSession:is_attached()

Check whether this session is attached correctly. Note: It must be the same instance that :attach() was called on, not a copy.

Returns: TypeGuard<finni.core.ActiveSession>

ActiveSession:opts()

Turn the session object into opts for snapshot restore/save operations

Returns: (finni.core.Session.Init.Paths&finni.core.Session.Init.Autosave&finni.core.Session.Init.Meta&finni.core.snapshot.CreateOpts)

ActiveSession:info()

Get information about this session

Returns: finni.core.ActiveSessionInfo

ActiveSession:delete(`opts`)

Delete a saved session

Parameters:

opts? (finni.SideEffects.Notify&finni.SideEffects.SilenceErrors)

Table fields:
- notify? boolean
  Notify on success
- silence_errors? boolean
  Don't error during this operation

ActiveSession:attach()

Attach this session. If it was loaded from a snapshot file, you must ensure you restore the snapshot (:restore()) before calling this method. It's fine to attach an already attached session.

Returns: finni.core.ActiveSession

ActiveSession:save(`opts`)

Save this session following its configured configuration. Note: Any save configuration must be applied via Session.update(opts) before callig this method since all session-specific options that might be contained in opts are overridden with ones configured for the session.

Parameters:

opts unknown
Success notification setting plus options that need to be passed through to pre_save/post_save hooks.

Returns: success boolean

ActiveSession:autosave(`opts`, `force`)

Parameters:

opts? (finni.SideEffects.Notify&finni.core.PassthroughOpts)

Table fields:
- notify? boolean
  Notify on success
force? boolean
Force snapshot to be saved, regardless of autosave config

ActiveSession:detach(`reason`, `opts`)

Detach from this session. Ensure the session is attached before trying to detach, otherwise you'll receive an error. Hint: If you are sure the session should be attached, but still receive an error, ensure that you call detach() on the specific session instance you called :attach() on before, not a copy. @param self ActiveSession

Parameters:

reason (finni.core.Session.DetachReasonBuiltin|string)
A reason for detaching, also passed to detach hooks. Only inbuilt reasons influence behavior by default.
opts (finni.core.Session.DetachOpts&finni.core.PassthroughOpts)
Influence side effects. reset removes all associated resources. save overrides autosave behavior.

Table fields:
- reset? boolean
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.
- save? boolean
  Save/override autosave config for affected sessions before the operation

Returns: idle_session finni.core.IdleSession
Same data table, but now representing an idle session again.

ActiveSession:forget(`self`)

Mark a tab session as invalid (i.e. remembered as attached, but its tab is gone). Removes associated resources, skips autosave.

Parameters:

self finni.core.ActiveSession<finni.core.Session.TabTarget>
Active tab session to forget about. Errors if attempted with global sessions.

Table fields:
- session_file string
  Path to the session file
- state_dir string
  Path to the directory holding session-associated data
- context_dir string
  Directory for shared state between all sessions in the same context (dir for manual sessions, project dir for autosessions)
- autosave_enabled boolean
  Autosave this attached session in intervals and when detaching
- autosave_interval integer
  Seconds between autosaves of this session, if enabled.
- autosave_notify? boolean
  Trigger a notification when autosaving this session. Defaults to true.
- on_attach? finni.core.Session.AttachHook
  A function that's called when attaching to this session. No global default.
- on_detach? finni.core.Session.DetachHook
  A function that's called when detaching from this session. No global default.
- meta? table
  External data remembered in association with this session. Useful to build on top of the core API.
- options? string[]
  Save and restore these Neovim (global|buffer|tab|window) options.
- buf_filter? finni.BufFilter
  Function that decides whether a buffer should be included in a snapshot.
- tab_buf_filter? finni.TabBufFilter
  Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
- modified? (boolean|"auto")
  Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
- jumps? boolean
  Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
- changelist? boolean
  Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).
  
  Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
- global_marks? boolean
  Save/load global marks (A-Z, not 0-9 currently).
  
  Only in global sessions.
- local_marks? boolean
  Save/load buffer-specific (local) marks.
  
  Note: Enable this if you track the changelist.
- search_history? (integer|boolean)
  Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- command_history? (integer|boolean)
  Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- input_history? (integer|boolean)
  Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- expr_history? boolean
  Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- debug_history? boolean
  Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- tab_scoped boolean
- tabid? finni.core.TabID
- name string
- _on_attach finni.core.Session.AttachHook[]
- _on_detach finni.core.Session.DetachHook[]
- _aug integer
  Neovim augroup for this session
- _timer? uv.uv_timer_t
  Autosave timer, if enabled
- _setup_autosave fun(self: finni.core.ActiveSession<finni.core.Session.TabTarget>)

Returns: idle_session finni.core.IdleSession<finni.core.Session.TabTarget>

`finni.core.ActiveSessionInfo` (Class)

Represents the complete internal state of a session

Fields:

session_file string
Path to the session file
state_dir string
Path to the directory holding session-associated data
context_dir string
Directory for shared state between all sessions in the same context (dir for manual sessions, project dir for autosessions)
autosave_enabled boolean
When this session is attached, automatically save it in intervals. Defaults to false.
autosave_interval integer
Seconds between autosaves of this session, if enabled. Defaults to 60.
name string
Name of the session
tab_scoped boolean
Whether the session is tab-scoped
autosave_notify? boolean
Trigger a notification when autosaving this session. Defaults to true.
on_attach? finni.core.Session.AttachHook
A function that's called when attaching to this session. No global default.
on_detach? finni.core.Session.DetachHook
A function that's called when detaching from this session. No global default.
meta? table
External data remembered in association with this session. Useful to build on top of the core API.
options? string[]
Save and restore these Neovim (global|buffer|tab|window) options.
buf_filter? finni.BufFilter
Function that decides whether a buffer should be included in a snapshot.
tab_buf_filter? finni.TabBufFilter
Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
modified? (boolean|"auto")
Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
jumps? boolean
Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
changelist? boolean
Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).

Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
global_marks? boolean
Save/load global marks (A-Z, not 0-9 currently).

Only in global sessions.
local_marks? boolean
Save/load buffer-specific (local) marks.

Note: Enable this if you track the changelist.
search_history? (integer|boolean)
Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
command_history? (integer|boolean)
Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
input_history? (integer|boolean)
Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
expr_history? boolean
Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
debug_history? boolean
Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
tabid? (finni.core.TabID|true)
Tab number the session is attached to, if any. Can be true, which indicates it's a tab-scoped session that has not been restored yet - although not when requesting via the API

`finni.core.AnonymousMark` (Class)

Fields:

[1] integer
Line number
[2] integer
Column number

`finni.core.BufUUID` (Alias)

Type: string

An internal UUID that is used to keep track of buffers between snapshot restorations.

`finni.core.FileMark` (Class)

Fields:

[1] sub<string,"">
Absolute path to file this mark references
[2] integer
Line number
[3] integer
Column number

`finni.core.IdleSession` (Class)

A general session config that can be attached, turning it into an active session.

Fields:

session_file string
Path to the session file
state_dir string
Path to the directory holding session-associated data
context_dir string
Directory for shared state between all sessions in the same context (dir for manual sessions, project dir for autosessions)
autosave_enabled boolean
When this session is attached, automatically save it in intervals. Defaults to false.
autosave_interval integer
Seconds between autosaves of this session, if enabled. Defaults to 60.
name string
tab_scoped boolean
autosave_notify? boolean
Trigger a notification when autosaving this session. Defaults to true.
on_attach? finni.core.Session.AttachHook
A function that's called when attaching to this session. No global default.
on_detach? finni.core.Session.DetachHook
A function that's called when detaching from this session. No global default.
meta? table
External data remembered in association with this session. Useful to build on top of the core API.
options? string[]
Save and restore these Neovim (global|buffer|tab|window) options.
buf_filter? finni.BufFilter
Function that decides whether a buffer should be included in a snapshot.
tab_buf_filter? finni.TabBufFilter
Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
modified? (boolean|"auto")
Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
jumps? boolean
Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
changelist? boolean
Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).

Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
global_marks? boolean
Save/load global marks (A-Z, not 0-9 currently).

Only in global sessions.
local_marks? boolean
Save/load buffer-specific (local) marks.

Note: Enable this if you track the changelist.
search_history? (integer|boolean)
Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
command_history? (integer|boolean)
Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
input_history? (integer|boolean)
Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
expr_history? boolean
Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
debug_history? boolean
Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
tabid? finni.core.TabID

new(`name`, `session_file`, `state_dir`, `context_dir`, `opts`, `tabid`, `needs_restore`)

Parameters:

name string
session_file string
state_dir string
context_dir string
opts finni.core.Session.InitOptsWithMeta
tabid true
needs_restore true

Returns: finni.core.PendingSession<finni.core.Session.TabTarget>

from_snapshot(`name`, `session_file`, `state_dir`, `context_dir`, `opts`)

Create a new session by loading a snapshot, which you need to restore explicitly.

Parameters:

name string
session_file string
state_dir string
context_dir string
opts (finni.core.Session.InitOptsWithMeta&finni.SideEffects.SilenceErrors)

Table fields:
- autosave_enabled? boolean
  When this session is attached, automatically save it in intervals. Defaults to false.
- autosave_interval? integer
  Seconds between autosaves of this session, if enabled. Defaults to 60.
- autosave_notify? boolean
  Trigger a notification when autosaving this session. Defaults to true.
- on_attach? finni.core.Session.AttachHook
  A function that's called when attaching to this session. No global default.
- on_detach? finni.core.Session.DetachHook
  A function that's called when detaching from this session. No global default.
- options? string[]
  Save and restore these Neovim (global|buffer|tab|window) options.
- buf_filter? finni.BufFilter
  Function that decides whether a buffer should be included in a snapshot.
- tab_buf_filter? finni.TabBufFilter
  Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
- modified? (boolean|"auto")
  Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
- jumps? boolean
  Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
- changelist? boolean
  Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).
  
  Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
- global_marks? boolean
  Save/load global marks (A-Z, not 0-9 currently).
  
  Only in global sessions.
- local_marks? boolean
  Save/load buffer-specific (local) marks.
  
  Note: Enable this if you track the changelist.
- search_history? (integer|boolean)
  Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- command_history? (integer|boolean)
  Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- input_history? (integer|boolean)
  Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- expr_history? boolean
  Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- debug_history? boolean
  Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- meta? table
  External data remembered in association with this session. Useful to build on top of the core API.
- silence_errors? boolean
  Don't error during this operation

Returns:

loaded_session? finni.core.PendingSession
Session object, if the snapshot could be loaded
snapshot? finni.core.Snapshot
Snapshot data, if it could be loaded

IdleSession:add_hook(`event`, `hook`)

Parameters:

event "detach"
hook finni.core.Session.DetachHook

Returns: self

IdleSession:update(`opts`)

Update modifiable options without attaching/detaching a session

Parameters:

opts finni.core.Session.InitOptsWithMeta

Returns: modified boolean
Indicates whether any config modifications occurred

IdleSession:restore(`opts`, `snapshot`)

Restore a snapshot from disk or memory

Parameters:

opts? (finni.core.Session.RestoreOpts&finni.core.PassthroughOpts)

Table fields:
- reset? boolean
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.
- silence_errors? boolean
  Don't error during this operation
snapshot? finni.core.Snapshot
Snapshot data to restore. If unspecified, loads from file.

Table fields:
- buffers finni.core.Snapshot.BufData[]
  Buffer-specific data like name, buffer options, local marks, changelist
- tabs finni.core.Snapshot.TabData[]
  Tab-specific and window layout data, including tab cwd and window-specific jumplists
- tab_scoped boolean
  Whether this snapshot was derived from a single tab
- global finni.core.Snapshot.GlobalData
  Global snapshot data like process CWD, global options and global marks
- modified? table<finni.core.BufUUID,true?>
  List of buffers (identified by internal UUID) whose unsaved modifications were backed up in the snapshot
- buflist string[]
  List of named buffers that are referenced somewhere in this snapshot. Used to reduce repetition of buffer paths in save file, especially lists of named marks (jumplist, quickfix and location lists).

Returns:

self finni.core.IdleSession
The object itself, but now attachable
success boolean
Whether restoration was successful. Only sensible when silence_errors is true.

IdleSession:is_attached()

Check whether this session is attached correctly. Note: It must be the same instance that :attach() was called on, not a copy.

Returns: TypeGuard<finni.core.ActiveSession>

IdleSession:opts()

Turn the session object into opts for snapshot restore/save operations

Returns: (finni.core.Session.Init.Paths&finni.core.Session.Init.Autosave&finni.core.Session.Init.Meta&finni.core.snapshot.CreateOpts)

IdleSession:info()

Get information about this session

Returns: finni.core.ActiveSessionInfo

IdleSession:delete(`opts`)

Delete a saved session

Parameters:

opts? (finni.SideEffects.Notify&finni.SideEffects.SilenceErrors)

Table fields:
- notify? boolean
  Notify on success
- silence_errors? boolean
  Don't error during this operation

IdleSession:attach()

Attach this session. If it was loaded from a snapshot file, you must ensure you restore the snapshot (:restore()) before calling this method. It's fine to attach an already attached session.

Returns: finni.core.ActiveSession

IdleSession:save(`opts`)

Save this session following its configured configuration. Note: Any save configuration must be applied via Session.update(opts) before callig this method since all session-specific options that might be contained in opts are overridden with ones configured for the session.

Parameters:

opts unknown
Success notification setting plus options that need to be passed through to pre_save/post_save hooks.

Returns: success boolean

`finni.core.layout.WinInfo` (Class)

Window-specific snapshot data

Fields:

bufname string
The name of the buffer that's displayed in the window.
bufuuid finni.core.BufUUID
The buffer's UUID to track it over multiple sessions.
current boolean
Whether the window was the active one when saved.
view vim.fn.winsaveview.ret
Cursor position in file, relative position of file in window, curswant and other state
width integer
Width of the window in number of columns.
height integer
Height of the window in number of rows.
options table<string,any>
Window-scoped options.
old_winid finni.core.WinID
Window ID when snapshot was saved. Used to keep track of individual windows, especially loclist window restoration.
extension_data any
If the window is supported by an extension, the data it needs to remember.
cursor? finni.core.AnonymousMark
(row, col) tuple of the cursor position, mark-like => (1, 0)-indexed. Deprecated in favor of view.

Table fields:
- [1] integer
  Line number
- [2] integer
  Column number
cwd? string
If a local working directory was set for the window, its path.
extension? string
If the window is supported by an extension, the name of the extension.
jumps? (finni.core.layout.WinInfo.JumplistEntry[],integer)
Window-local jumplist, number of steps from last entry to currently active one
alt? integer
Index of the alternate file for this window in buflist, if any
loclist_win? finni.core.WinID
Present for loclist windows. Window ID of the associated window, the one that opens selections (filewinid).
loclists? (finni.core.Snapshot.QFList[],integer)
Location list stack and position of currently active one.

`finni.core.layout.WinInfo.JumplistEntry` (Class)

Fields:

[1] integer
Index of absolute path to file this mark references in buflist
[2] integer
Line number
[3] integer
Column number

`finni.core.layout.WinLayout` (Alias)

Type: (finni.core.layout.WinLayoutLeaf|finni.core.layout.WinLayoutBranch)

`finni.core.layout.WinLayoutBranch` (Class)

Fields:

[1] ("row"|"col")
Node type
[2] (finni.core.layout.WinLayoutLeaf|finni.core.layout.WinLayoutBranch)[]
children

`finni.core.layout.WinLayoutLeaf` (Class)

Fields:

[1] "leaf"
Node type
[2] finni.core.layout.WinInfo
Saved window info

Table fields:
- bufname string
  The name of the buffer that's displayed in the window.
- bufuuid finni.core.BufUUID
  The buffer's UUID to track it over multiple sessions.
- current boolean
  Whether the window was the active one when saved.
- cursor? finni.core.AnonymousMark
  (row, col) tuple of the cursor position, mark-like => (1, 0)-indexed. Deprecated in favor of view.
- view vim.fn.winsaveview.ret
  Cursor position in file, relative position of file in window, curswant and other state
- width integer
  Width of the window in number of columns.
- height integer
  Height of the window in number of rows.
- options table<string,any>
  Window-scoped options.
- old_winid finni.core.WinID
  Window ID when snapshot was saved. Used to keep track of individual windows, especially loclist window restoration.
- cwd? string
  If a local working directory was set for the window, its path.
- extension_data any
  If the window is supported by an extension, the data it needs to remember.
- extension? string
  If the window is supported by an extension, the name of the extension.
- jumps? (finni.core.layout.WinInfo.JumplistEntry[],integer)
  Window-local jumplist, number of steps from last entry to currently active one
- alt? integer
  Index of the alternate file for this window in buflist, if any
- loclist_win? finni.core.WinID
  Present for loclist windows. Window ID of the associated window, the one that opens selections (filewinid).
- loclists? (finni.core.Snapshot.QFList[],integer)
  Location list stack and position of currently active one.

`finni.core.PassthroughOpts` (Alias)

Type: table

Indicates that any unhandled opts are also passed through to custom hooks.

`finni.core.PendingSession` (Class)

Represents a session that has been loaded from a snapshot and needs to be applied still before being able to attach it.

Fields:

session_file string
Path to the session file
state_dir string
Path to the directory holding session-associated data
context_dir string
Directory for shared state between all sessions in the same context (dir for manual sessions, project dir for autosessions)
autosave_enabled boolean
When this session is attached, automatically save it in intervals. Defaults to false.
autosave_interval integer
Seconds between autosaves of this session, if enabled. Defaults to 60.
name string
tab_scoped boolean
needs_restore true
Indicates this session has been loaded from a snapshot, but not restored yet. This session object cannot be attached yet, it needs to be restored first.
autosave_notify? boolean
Trigger a notification when autosaving this session. Defaults to true.
on_attach? finni.core.Session.AttachHook
A function that's called when attaching to this session. No global default.
on_detach? finni.core.Session.DetachHook
A function that's called when detaching from this session. No global default.
meta? table
External data remembered in association with this session. Useful to build on top of the core API.
options? string[]
Save and restore these Neovim (global|buffer|tab|window) options.
buf_filter? finni.BufFilter
Function that decides whether a buffer should be included in a snapshot.
tab_buf_filter? finni.TabBufFilter
Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
modified? (boolean|"auto")
Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
jumps? boolean
Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
changelist? boolean
Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).

Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
global_marks? boolean
Save/load global marks (A-Z, not 0-9 currently).

Only in global sessions.
local_marks? boolean
Save/load buffer-specific (local) marks.

Note: Enable this if you track the changelist.
search_history? (integer|boolean)
Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
command_history? (integer|boolean)
Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
input_history? (integer|boolean)
Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
expr_history? boolean
Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
debug_history? boolean
Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
tabid? finni.core.TabID

new(`name`, `session_file`, `state_dir`, `context_dir`, `opts`, `tabid`, `needs_restore`)

Parameters:

name string
session_file string
state_dir string
context_dir string
opts finni.core.Session.InitOptsWithMeta
tabid true
needs_restore true

Returns: finni.core.PendingSession<finni.core.Session.TabTarget>

from_snapshot(`name`, `session_file`, `state_dir`, `context_dir`, `opts`)

Create a new session by loading a snapshot, which you need to restore explicitly.

Parameters:

name string
session_file string
state_dir string
context_dir string
opts (finni.core.Session.InitOptsWithMeta&finni.SideEffects.SilenceErrors)

Table fields:
- autosave_enabled? boolean
  When this session is attached, automatically save it in intervals. Defaults to false.
- autosave_interval? integer
  Seconds between autosaves of this session, if enabled. Defaults to 60.
- autosave_notify? boolean
  Trigger a notification when autosaving this session. Defaults to true.
- on_attach? finni.core.Session.AttachHook
  A function that's called when attaching to this session. No global default.
- on_detach? finni.core.Session.DetachHook
  A function that's called when detaching from this session. No global default.
- options? string[]
  Save and restore these Neovim (global|buffer|tab|window) options.
- buf_filter? finni.BufFilter
  Function that decides whether a buffer should be included in a snapshot.
- tab_buf_filter? finni.TabBufFilter
  Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
- modified? (boolean|"auto")
  Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
- jumps? boolean
  Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
- changelist? boolean
  Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).
  
  Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
- global_marks? boolean
  Save/load global marks (A-Z, not 0-9 currently).
  
  Only in global sessions.
- local_marks? boolean
  Save/load buffer-specific (local) marks.
  
  Note: Enable this if you track the changelist.
- search_history? (integer|boolean)
  Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- command_history? (integer|boolean)
  Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- input_history? (integer|boolean)
  Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- expr_history? boolean
  Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- debug_history? boolean
  Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- meta? table
  External data remembered in association with this session. Useful to build on top of the core API.
- silence_errors? boolean
  Don't error during this operation

Returns:

loaded_session? finni.core.PendingSession
Session object, if the snapshot could be loaded
snapshot? finni.core.Snapshot
Snapshot data, if it could be loaded

PendingSession:add_hook(`event`, `hook`)

Parameters:

event "detach"
hook finni.core.Session.DetachHook

Returns: self

PendingSession:update(`opts`)

Update modifiable options without attaching/detaching a session

Parameters:

opts finni.core.Session.InitOptsWithMeta

Returns: modified boolean
Indicates whether any config modifications occurred

PendingSession:restore(`opts`, `snapshot`)

Restore a snapshot from disk or memory

Parameters:

opts? (finni.core.Session.RestoreOpts&finni.core.PassthroughOpts)

Table fields:
- reset? boolean
  When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.
- silence_errors? boolean
  Don't error during this operation
snapshot? finni.core.Snapshot
Snapshot data to restore. If unspecified, loads from file.

Table fields:
- buffers finni.core.Snapshot.BufData[]
  Buffer-specific data like name, buffer options, local marks, changelist
- tabs finni.core.Snapshot.TabData[]
  Tab-specific and window layout data, including tab cwd and window-specific jumplists
- tab_scoped boolean
  Whether this snapshot was derived from a single tab
- global finni.core.Snapshot.GlobalData
  Global snapshot data like process CWD, global options and global marks
- modified? table<finni.core.BufUUID,true?>
  List of buffers (identified by internal UUID) whose unsaved modifications were backed up in the snapshot
- buflist string[]
  List of named buffers that are referenced somewhere in this snapshot. Used to reduce repetition of buffer paths in save file, especially lists of named marks (jumplist, quickfix and location lists).

Returns:

self finni.core.IdleSession
The object itself, but now attachable
success boolean
Whether restoration was successful. Only sensible when silence_errors is true.

PendingSession:is_attached()

Check whether this session is attached correctly. Note: It must be the same instance that :attach() was called on, not a copy.

Returns: TypeGuard<finni.core.ActiveSession>

PendingSession:opts()

Turn the session object into opts for snapshot restore/save operations

Returns: (finni.core.Session.Init.Paths&finni.core.Session.Init.Autosave&finni.core.Session.Init.Meta&finni.core.snapshot.CreateOpts)

PendingSession:info()

Get information about this session

Returns: finni.core.ActiveSessionInfo

PendingSession:delete(`opts`)

Delete a saved session

Parameters:

opts? (finni.SideEffects.Notify&finni.SideEffects.SilenceErrors)

Table fields:
- notify? boolean
  Notify on success
- silence_errors? boolean
  Don't error during this operation

`finni.core.Session.AttachHook` (Alias)

Type: fun(session: finni.core.IdleSession)

Attach hooks can inspect the session. Modifying it in-place should work, but it's not officially supported.

`finni.core.Session.DetachHook` (Alias)

Type: (fun(session: finni.core.ActiveSession, reason: (finni.core.Session.DetachReasonBuiltin|string), opts: (finni.core.Session.DetachOpts&finni.core.PassthroughOpts)) -> (finni.core.Session.DetachOpts&finni.core.PassthroughOpts))?

Detach hooks can modify detach opts in place or return new ones. They can inspect the session. Modifying it in-place should work, but it's not officially supported.

`finni.core.Session.DetachOpts` (Alias)

Type: (finni.SideEffects.Reset&finni.SideEffects.Save)

Options for detaching sessions

Fields:

reset? boolean
When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.
save? boolean
Save/override autosave config for affected sessions before the operation

`finni.core.Session.DetachReasonBuiltin` (Alias)

Detach reasons are passed to avoid unintended side effects during operations. They are passed to detach hooks as well. These are the ones built in to the core session handling.

`finni.core.Session.Init.Autosave` (Class)

Fields:

autosave_enabled? boolean
When this session is attached, automatically save it in intervals. Defaults to false.
autosave_interval? integer
Seconds between autosaves of this session, if enabled. Defaults to 60.
autosave_notify? boolean
Trigger a notification when autosaving this session. Defaults to true.

`finni.core.Session.Init.Hooks` (Class)

Fields:

on_attach? finni.core.Session.AttachHook
A function that's called when attaching to this session. No global default.
on_detach? finni.core.Session.DetachHook
A function that's called when detaching from this session. No global default.

`finni.core.Session.Init.Meta` (Class)

Fields:

meta? table
External data remembered in association with this session. Useful to build on top of the core API.

`finni.core.Session.Init.Paths` (Class)

Fields:

session_file string
Path to the session file
state_dir string
Path to the directory holding session-associated data
context_dir string
Directory for shared state between all sessions in the same context (dir for manual sessions, project dir for autosessions)

`finni.core.Session.InitOpts` (Alias)

Type: (finni.core.Session.Init.Autosave&finni.core.Session.Init.Hooks&finni.core.snapshot.CreateOpts)

Options to influence how an attached session is handled.

Fields:

autosave_enabled? boolean
When this session is attached, automatically save it in intervals. Defaults to false.
autosave_interval? integer
Seconds between autosaves of this session, if enabled. Defaults to 60.
autosave_notify? boolean
Trigger a notification when autosaving this session. Defaults to true.
on_attach? finni.core.Session.AttachHook
A function that's called when attaching to this session. No global default.
on_detach? finni.core.Session.DetachHook
A function that's called when detaching from this session. No global default.
options? string[]
Save and restore these Neovim (global|buffer|tab|window) options.
buf_filter? finni.BufFilter
Function that decides whether a buffer should be included in a snapshot.
tab_buf_filter? finni.TabBufFilter
Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
modified? (boolean|"auto")
Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
jumps? boolean
Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
changelist? boolean
Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).

Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
global_marks? boolean
Save/load global marks (A-Z, not 0-9 currently).

Only in global sessions.
local_marks? boolean
Save/load buffer-specific (local) marks.

Note: Enable this if you track the changelist.
search_history? (integer|boolean)
Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
command_history? (integer|boolean)
Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
input_history? (integer|boolean)
Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
expr_history? boolean
Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
debug_history? boolean
Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.

`finni.core.Session.InitOptsWithMeta` (Alias)

Type: (finni.core.Session.InitOpts&finni.core.Session.Init.Meta)

Options to influence how an attached session is handled plus meta field, which can only be populated by passing it to the session constructor and is useful for custom session handling.

Fields:

autosave_enabled? boolean
When this session is attached, automatically save it in intervals. Defaults to false.
autosave_interval? integer
Seconds between autosaves of this session, if enabled. Defaults to 60.
autosave_notify? boolean
Trigger a notification when autosaving this session. Defaults to true.
on_attach? finni.core.Session.AttachHook
A function that's called when attaching to this session. No global default.
on_detach? finni.core.Session.DetachHook
A function that's called when detaching from this session. No global default.
options? string[]
Save and restore these Neovim (global|buffer|tab|window) options.
buf_filter? finni.BufFilter
Function that decides whether a buffer should be included in a snapshot.
tab_buf_filter? finni.TabBufFilter
Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
modified? (boolean|"auto")
Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
jumps? boolean
Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
changelist? boolean
Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).

Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
global_marks? boolean
Save/load global marks (A-Z, not 0-9 currently).

Only in global sessions.
local_marks? boolean
Save/load buffer-specific (local) marks.

Note: Enable this if you track the changelist.
search_history? (integer|boolean)
Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
command_history? (integer|boolean)
Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
input_history? (integer|boolean)
Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
expr_history? boolean
Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
debug_history? boolean
Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
meta? table
External data remembered in association with this session. Useful to build on top of the core API.

`finni.core.Session.RestoreOpts` (Alias)

Type: (finni.SideEffects.Reset&finni.SideEffects.SilenceErrors)

Options for basic snapshot restoration (different from session loading!). Note that reset here does not handle detaching other active sessions, it really resets everything if set to true. If set to false, opens a new tab. Handle with care!

Fields:

reset? boolean
When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.
silence_errors? boolean
Don't error during this operation

`finni.core.Session.TabTarget` (Class)

The associated session is tab-scoped to this specific tab

Fields:

tab_scoped true
tabid finni.core.TabID

`finni.core.Snapshot` (Class)

A snapshot of nvim's state.

Fields:

buffers finni.core.Snapshot.BufData[]
Buffer-specific data like name, buffer options, local marks, changelist

Table fields:
- name string
  Name of the buffer, usually its path. Can be empty when unsaved modifications are backed up.
- loaded boolean
  Whether the buffer was loaded.
- options table<string,any>
  Buffer-specific nvim options.
- last_pos finni.core.AnonymousMark
  Position of the cursor when this buffer was last shown in a window (" mark). Only updated once a buffer becomes invisible. Visible buffer cursors are backed up in the window layout data.
- uuid string
  A buffer-specific UUID intended to track it between sessions. Required to save/restore unnamed buffers.
- in_win boolean
  Whether the buffer is visible in at least one window.
- changelist? (finni.core.Snapshot.BufData.ChangelistItem[],integer)
  Changelist and changelist position (backwards from most recent entry) for this buffer. Position is always 0 when invisible buffers are saved.
- marks? table<string,finni.core.AnonymousMark?>
  Saved buffer-local marks, if enabled
- bt? ("acwrite"|"help"|"nofile"|"nowrite"|"quickfix"|"terminal"...)
  buftype option of buffer. Unset if empty ("").
tabs finni.core.Snapshot.TabData[]
Tab-specific and window layout data, including tab cwd and window-specific jumplists

Table fields:
- options table<string,any>
  Tab-specific nvim options. Currently only cmdheight.
- wins finni.core.layout.WinLayout
  Window layout enriched with window-specific snapshot data
- cwd? string
  Tab-local cwd, if different from the global one or a tab-scoped snapshot
- current? boolean
tab_scoped boolean
Whether this snapshot was derived from a single tab
global finni.core.Snapshot.GlobalData
Global snapshot data like process CWD, global options and global marks

Table fields:
- cwd string
  Nvim's global cwd.
- height integer
  vim.o.lines - vim.o.cmdheight
- width integer
  vim.o.columns
- options table<string,any>
  Global nvim options
- marks? table<string,finni.core.FileMark?>
  Saved global marks, if enabled
- search_history boolean
  Whether search history was saved in session-associated ShaDa file. If enabled, corresponding history in nvim process should be cleared before loading.
- command_history boolean
  Whether command history was saved in session-associated ShaDa file. If enabled, corresponding history in nvim process should be cleared before loading.
- input_history boolean
  Whether input history was saved in session-associated ShaDa file. If enabled, corresponding history in nvim process should be cleared before loading.
- expr_history boolean
  Whether expression history was saved in session-associated ShaDa file. If enabled, corresponding history in nvim process should be cleared before loading.
- debug_history boolean
  Whether debug history was saved in session-associated ShaDa file. If enabled, corresponding history in nvim process should be cleared before loading.
buflist string[]
List of named buffers that are referenced somewhere in this snapshot. Used to reduce repetition of buffer paths in save file, especially lists of named marks (jumplist, quickfix and location lists).
modified? table<finni.core.BufUUID,true?>
List of buffers (identified by internal UUID) whose unsaved modifications were backed up in the snapshot

`finni.core.Snapshot.BufData` (Class)

Buffer-specific snapshot data like path, loaded state, options and last cursor position.

Fields:

name string
Name of the buffer, usually its path. Can be empty when unsaved modifications are backed up.
loaded boolean
Whether the buffer was loaded.
options table<string,any>
Buffer-specific nvim options.
last_pos finni.core.AnonymousMark
Position of the cursor when this buffer was last shown in a window (" mark). Only updated once a buffer becomes invisible. Visible buffer cursors are backed up in the window layout data.

Table fields:
- [1] integer
  Line number
- [2] integer
  Column number
uuid string
A buffer-specific UUID intended to track it between sessions. Required to save/restore unnamed buffers.
in_win boolean
Whether the buffer is visible in at least one window.
changelist? (finni.core.Snapshot.BufData.ChangelistItem[],integer)
Changelist and changelist position (backwards from most recent entry) for this buffer. Position is always 0 when invisible buffers are saved.
marks? table<string,finni.core.AnonymousMark?>
Saved buffer-local marks, if enabled
bt? ("acwrite"|"help"|"nofile"|"nowrite"|"quickfix"|"terminal"...)
buftype option of buffer. Unset if empty ("").

`finni.core.Snapshot.BufData.ChangelistItem` (Class)

Fields:

[1] integer
Line number
[2] integer
Column number

`finni.core.snapshot.CreateOpts` (Class)

Options to influence which data is included in a snapshot.

Fields:

options? string[]
Save and restore these Neovim (global|buffer|tab|window) options.
buf_filter? finni.BufFilter
Function that decides whether a buffer should be included in a snapshot.
tab_buf_filter? finni.TabBufFilter
Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
modified? (boolean|"auto")
Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
jumps? boolean
Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
changelist? boolean
Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).

Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
global_marks? boolean
Save/load global marks (A-Z, not 0-9 currently).

Only in global sessions.
local_marks? boolean
Save/load buffer-specific (local) marks.

Note: Enable this if you track the changelist.
search_history? (integer|boolean)
Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
command_history? (integer|boolean)
Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
input_history? (integer|boolean)
Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
expr_history? boolean
Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
debug_history? boolean
Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.

`finni.core.Snapshot.GlobalData` (Class)

Global snapshot data like cwd, height/width and global options.

Fields:

cwd string
Nvim's global cwd.
height integer
vim.o.lines - vim.o.cmdheight
width integer
vim.o.columns
options table<string,any>
Global nvim options
search_history boolean
Whether search history was saved in session-associated ShaDa file. If enabled, corresponding history in nvim process should be cleared before loading.
command_history boolean
Whether command history was saved in session-associated ShaDa file. If enabled, corresponding history in nvim process should be cleared before loading.
input_history boolean
Whether input history was saved in session-associated ShaDa file. If enabled, corresponding history in nvim process should be cleared before loading.
expr_history boolean
Whether expression history was saved in session-associated ShaDa file. If enabled, corresponding history in nvim process should be cleared before loading.
debug_history boolean
Whether debug history was saved in session-associated ShaDa file. If enabled, corresponding history in nvim process should be cleared before loading.
marks? table<string,finni.core.FileMark?>
Saved global marks, if enabled

`finni.core.Snapshot.QFList` (Class)

Represents a quickfix/location list

Fields:

idx integer
Current position in list
title string
Title of list
context any
Arbitrary context for this list, may be used by plugins
quickfixtextfunc string
Function to customize the displayed text
items finni.core.Snapshot.QFListItem[]
Items in the list

Table fields:
- filename? integer
  Index of path of the file this entry points to in buflist
- module string
  Module name (?)
- lnum integer
  Referenced line in the file, 1-indexed
- end_lnum? integer
  For multiline items, last referenced line
- col integer
  Referenced column in the line of the file, also 1-indexed
- end_col? integer
  For ranged items, last referenced column number
- vcol boolean
  Whether col is visual index or byte index
- nr integer
  Item index in the list
- pattern string
  Search pattern used to locate the item
- text string
  Item description
- type string
  Type of the item (?)
- valid boolean
  Whether error message was recognized (?)
efm? string
Error format string to use for parsing lines

`finni.core.Snapshot.TabData` (Class)

Tab-specific (options, cwd) and window layout snapshot data.

Fields:

options table<string,any>
Tab-specific nvim options. Currently only cmdheight.
wins finni.core.layout.WinLayout
Window layout enriched with window-specific snapshot data
cwd? string
Tab-local cwd, if different from the global one or a tab-scoped snapshot
current? boolean

`finni.core.TabID` (Alias)

Type: integer

Nvim tab ID

`finni.core.WinID` (Alias)

Type: integer

Nvim window ID

`finni.log.Level` (Alias)

Log level name in uppercase, for internal references and log output

`finni.log.Line` (Class)

Log call information passed to handler

Fields:

level finni.log.Level
Name of log level, uppercase
message string
Final, formatted log message
timestamp integer
UNIX timestamp of log message
hrtime number
High-resolution time of log message ([ns], arbitrary anchor)
src_path string
Absolute path to the file the log call originated from
src_line integer
Line in src_path the log call originated from

`finni.pickers.PickerRawOverrides` (Class)

Fields:

default table
Override any (picker plugin-specific) options passed to all picker types.
manual table
Override any (picker plugin-specific) options passed to the manual session picker.
auto table
Override any (picker plugin-specific) options passed to the autosession picker.
auto_all table
Override any (picker plugin-specific) options passed to the global autosession picker.
project table
Override any (picker plugin-specific) options passed to the project autosession picker.

`finni.session.DeleteOpts` (Alias)

Type: (finni.session.DirParam&finni.SideEffects.Notify&finni.SideEffects.Reset&finni.SideEffects.SilenceErrors)

API options for session.delete

Fields:

dir? string
Name of session directory (overrides config.dir)
notify? boolean
Notify on success
reset? boolean
When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.
silence_errors? boolean
Don't error during this operation

`finni.session.DirParam` (Class)

Fields:

dir? string
Name of session directory (overrides config.dir)

`finni.session.LoadOpts` (Alias)

Type: (finni.session.DirParam&finni.core.Session.InitOptsWithMeta&finni.SideEffects.Attach&finni.SideEffects.ResetAuto&finni.SideEffects.Save&finni.SideEffects.SilenceErrors)

API options for session.load

Fields:

dir? string
Name of session directory (overrides config.dir)
autosave_enabled? boolean
When this session is attached, automatically save it in intervals. Defaults to false.
autosave_interval? integer
Seconds between autosaves of this session, if enabled. Defaults to 60.
autosave_notify? boolean
Trigger a notification when autosaving this session. Defaults to true.
on_attach? finni.core.Session.AttachHook
A function that's called when attaching to this session. No global default.
on_detach? finni.core.Session.DetachHook
A function that's called when detaching from this session. No global default.
options? string[]
Save and restore these Neovim (global|buffer|tab|window) options.
buf_filter? finni.BufFilter
Function that decides whether a buffer should be included in a snapshot.
tab_buf_filter? finni.TabBufFilter
Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
modified? (boolean|"auto")
Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
jumps? boolean
Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
changelist? boolean
Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).

Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
global_marks? boolean
Save/load global marks (A-Z, not 0-9 currently).

Only in global sessions.
local_marks? boolean
Save/load buffer-specific (local) marks.

Note: Enable this if you track the changelist.
search_history? (integer|boolean)
Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
command_history? (integer|boolean)
Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
input_history? (integer|boolean)
Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
expr_history? boolean
Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
debug_history? boolean
Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
meta? table
External data remembered in association with this session. Useful to build on top of the core API.
attach? boolean
Attach to/stay attached to session after operation
reset? (boolean|"auto")
When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot. auto resets only for global sessions.
save? boolean
Save/override autosave config for affected sessions before the operation
silence_errors? boolean
Don't error during this operation

`finni.session.SaveOpts` (Alias)

Type: (finni.session.DirParam&finni.core.Session.InitOptsWithMeta&finni.SideEffects.Attach&finni.SideEffects.Notify&finni.SideEffects.Reset)

API options for session.save

Fields:

dir? string
Name of session directory (overrides config.dir)
autosave_enabled? boolean
When this session is attached, automatically save it in intervals. Defaults to false.
autosave_interval? integer
Seconds between autosaves of this session, if enabled. Defaults to 60.
autosave_notify? boolean
Trigger a notification when autosaving this session. Defaults to true.
on_attach? finni.core.Session.AttachHook
A function that's called when attaching to this session. No global default.
on_detach? finni.core.Session.DetachHook
A function that's called when detaching from this session. No global default.
options? string[]
Save and restore these Neovim (global|buffer|tab|window) options.
buf_filter? finni.BufFilter
Function that decides whether a buffer should be included in a snapshot.
tab_buf_filter? finni.TabBufFilter
Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
modified? (boolean|"auto")
Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
jumps? boolean
Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
changelist? boolean
Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).

Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
global_marks? boolean
Save/load global marks (A-Z, not 0-9 currently).

Only in global sessions.
local_marks? boolean
Save/load buffer-specific (local) marks.

Note: Enable this if you track the changelist.
search_history? (integer|boolean)
Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
command_history? (integer|boolean)
Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
input_history? (integer|boolean)
Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
expr_history? boolean
Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
debug_history? boolean
Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
meta? table
External data remembered in association with this session. Useful to build on top of the core API.
attach? boolean
Attach to/stay attached to session after operation
notify? boolean
Notify on success
reset? boolean
When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.

`finni.SideEffects.Attach` (Class)

Fields:

attach? boolean
Attach to/stay attached to session after operation

`finni.SideEffects.Notify` (Class)

Fields:

notify? boolean
Notify on success

`finni.SideEffects.Reset` (Class)

Fields:

reset? boolean
When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot.

`finni.SideEffects.ResetAuto` (Class)

Fields:

reset? (boolean|"auto")
When detaching a session in the process, unload associated resources/reset everything during the operation when restoring a snapshot. auto resets only for global sessions.

`finni.SideEffects.Save` (Class)

Fields:

save? boolean
Save/override autosave config for affected sessions before the operation

`finni.SideEffects.SilenceErrors` (Class)

Fields:

silence_errors? boolean
Don't error during this operation

`finni.TabBufFilter` (Alias)

Type: fun(tabpage: integer, bufnr: integer, opts: finni.core.snapshot.CreateOpts) -> boolean

Function that decides whether a buffer should be included in a tab-scoped snapshot. BufFilter is called first, this is to refine acceptable buffers only.

`finni.UserConfig.autosession` (Class)

Configure autosession behavior and contents

Fields:

config? finni.core.Session.InitOpts
Save/load configuration for autosessions. Definitions in here override the defaults in session.

Table fields:
- autosave_enabled? boolean
  When this session is attached, automatically save it in intervals. Defaults to false.
- autosave_interval? integer
  Seconds between autosaves of this session, if enabled. Defaults to 60.
- autosave_notify? boolean
  Trigger a notification when autosaving this session. Defaults to true.
- on_attach? finni.core.Session.AttachHook
  A function that's called when attaching to this session. No global default.
- on_detach? finni.core.Session.DetachHook
  A function that's called when detaching from this session. No global default.
- options? string[]
  Save and restore these Neovim (global|buffer|tab|window) options.
- buf_filter? finni.BufFilter
  Function that decides whether a buffer should be included in a snapshot.
- tab_buf_filter? finni.TabBufFilter
  Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
- modified? (boolean|"auto")
  Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
- jumps? boolean
  Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
- changelist? boolean
  Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).
  
  Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
- global_marks? boolean
  Save/load global marks (A-Z, not 0-9 currently).
  
  Only in global sessions.
- local_marks? boolean
  Save/load buffer-specific (local) marks.
  
  Note: Enable this if you track the changelist.
- search_history? (integer|boolean)
  Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- command_history? (integer|boolean)
  Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- input_history? (integer|boolean)
  Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.
  
  Only in global sessions.
- expr_history? boolean
  Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
- debug_history? boolean
  Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.
  
  Only in global sessions.
dir? string
Name of the directory to store autosession projects in. Interpreted relative to $XDG_STATE_HOME/$NVIM_APPNAME. Defaults to finni.
spec? finni.auto.SpecHook
This function implements the logic that derives the autosession spec from a path, usually the current working directory. If it returns an autosession spec, Finni automatically switches to the session's workspace root and tries to restore an existing matching session (matched by project name + session name). If it returns nothing, it's interpreted as "no autosession should be active".

It is called during various points in Finni's lifecycle:
1. Neovim startup (if startup autosessions are enabled)
2. When Neovim changes its global working directory
3. When a git branch is switched (if you have installed gitsigns.nvim)
If the return value does not match the current state, the currently active session (if any) is saved + closed and the new session (if any) restored.

The default implementation calls workspace, project_name, session_name, enabled and load_opts to piece together the specification. By overriding this config field, you can implement a custom logic. Mind that the other hooks have no effect then (unless you call them manually).
workspace? finni.auto.WorkspaceHook
Receive the effective nvim cwd, return workspace root and whether it is git-tracked.
project_name? finni.auto.ProjectNameHook
Receive the workspace root dir and whether it's git-tracked, return the project-specific session directory name.
session_name? finni.auto.SessionNameHook
Receive the effective nvim cwd, the workspace root, the project name and workspace repo git info and generate a session name.
enabled? finni.auto.EnabledHook
Receive the effective nvim cwd, the workspace root and project name and decide whether an autosession with this configuration should be active.
load_opts? finni.auto.LoadOptsHook
Influence how an autosession is loaded/persisted, e.g. load the session without attaching it or disable modified persistence. Merged on top of the default autosession configuration for this specific autosession only.

`finni.UserConfig.load` (Class)

Configure session list information detail and sort order

Fields:

detail? boolean
Show more detail about the sessions when selecting one to load. Disable if it causes lag.
order? ("modification_time"|"creation_time"|"filename")
Session list order

`finni.UserConfig.log` (Class)

Configure plugin logging

Fields:

level? ("trace"|"debug"|"info"|"warn"|"error"|"off")
Minimum level to log at. Defaults to warn.
notify_level? ("trace"|"debug"|"info"|"warn"|"error"|"off")
Minimum level to use vim.notify for. Defaults to warn.
notify_opts? table
Options to pass to vim.notify. Defaults to { title = "Finni" }
format? string
Log line format string. Note that this works like Python's f-strings. Defaults to [%(level)s %(dtime)s] %(message)s%(src_sep)s[%(src_path)s:%(src_line)s]. Available parameters:
- level Uppercase level name
- message Log message
- dtime Formatted date/time string
- hrtime Time in [ns] without absolute anchor
- src_path Path to the file that called the log function
- src_line Line in src_path that called the log function
- src_sep Whitespace between log line and source of call, 2 tabs for single line, newline + tab for multiline log messages
notify_format? string
Same as format, but for vim.notify message display. Defaults to %(message)s.
time_format? string
strftime format string used for rendering time of call. Defaults to %Y-%m-%d %H:%M:%S
handler? fun(line: finni.log.Line)

`finni.UserConfig.session` (Class)

Configure default session behavior and contents, affects both manual and autosessions.

Fields:

autosave_enabled? boolean
When this session is attached, automatically save it in intervals. Defaults to false.
autosave_interval? integer
Seconds between autosaves of this session, if enabled. Defaults to 60.
autosave_notify? boolean
Trigger a notification when autosaving this session. Defaults to true.
on_attach? finni.core.Session.AttachHook
A function that's called when attaching to this session. No global default.
on_detach? finni.core.Session.DetachHook
A function that's called when detaching from this session. No global default.
options? string[]
Save and restore these Neovim (global|buffer|tab|window) options.
buf_filter? finni.BufFilter
Function that decides whether a buffer should be included in a snapshot.
tab_buf_filter? finni.TabBufFilter
Function that decides whether a buffer should be included in a tab-scoped snapshot. buf_filter is called first, this is to refine acceptable buffers only.
modified? (boolean|"auto")
Save/load modified buffers and their undo history. If set to auto (default), does not save, but still restores modified buffers.
jumps? boolean
Save/load window-specific jumplists, including current position (yes, for all windows, not just the active one like with ShaDa). If set to auto (default), does not save, but still restores saved jumplists.
changelist? boolean
Save/load buffer-specific changelist (all buffers) and changelist position (visible buffers only).

Important: Enabling this causes buffer-local marks to be cleared during restoration. Consider tracking local_marks in addition to this.
global_marks? boolean
Save/load global marks (A-Z, not 0-9 currently).

Only in global sessions.
local_marks? boolean
Save/load buffer-specific (local) marks.

Note: Enable this if you track the changelist.
search_history? (integer|boolean)
Maximum number of search history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
command_history? (integer|boolean)
Maximum number of command history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
input_history? (integer|boolean)
Maximum number of input history items to persist. Defaults to false. If set to true, maps to the 'history' option.

Only in global sessions.
expr_history? boolean
Persist expression history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
debug_history? boolean
Persist debug history. Defaults to false. Note: Cannot set limit (currently), no direct support by neovim.

Only in global sessions.
dir? string
Name of the directory to store regular sessions in. Interpreted relative to $XDG_STATE_HOME/$NVIM_APPNAME.

similar to scope-specific ShaDa via 'shadafile' ↩

Name		Name	Last commit message	Last commit date
Latest commit History 256 Commits
.github		.github
doc		doc
lua		lua
plugin		plugin
scripts		scripts
templates		templates
tests		tests
.editorconfig		.editorconfig
.emmyrc.json		.emmyrc.json
.gitignore		.gitignore
.luacheckrc		.luacheckrc
.stylua.toml		.stylua.toml
.styluaignore		.styluaignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md

License

lkubb/finni.nvim

Folders and files

Latest commit

History

Repository files navigation

finni.nvim

Table of Contents

Introduction

✨ Features

⛓️ Dependencies

📦 Setup

vim.pack

lazy.nvim

mini.deps

🚀 Usage

Keymaps

Ex command

Pickers

Keybinds

Configuration

finni.pickers.PickerConfig (Class)

snacks.picker

finni.pickers.snacks (Module)

setup(opts)

manual_picker(opts)

auto_all_picker(opts)

auto_picker(opts, project_name)

project_picker(opts)

fzf-lua

finni.pickers.fzf_lua (Module)

setup(opts, register)

manual_picker(opts)

auto_all_picker(opts)

auto_picker(opts, project_name)

project_picker(opts)

mini.pick

finni.pickers.mini_pick (Module)

setup(opts, register)

manual_picker(opts)

auto_all_picker(opts)

auto_picker(opts, project_name)

project_picker(opts)

telescope.nvim

finni.pickers.telescope (Module)

setup(opts)

manual_picker(opts)

auto_all_picker(opts)

auto_picker(opts, project_name)

project_picker(opts)

👤 Concepts

❗ Limitations and caveats

⚙️ Configuration

Defaults

autosession

Table fields

extensions

load

Table fields

log

Table fields

session

Table fields

📒 Recipes

Tab-scoped Sessions

Custom Extension

🔌 API

finni.session (Module)

save(name, opts)

save_tab(name, opts)

save_all(opts)

load(name, opts)

detach(target, reason, opts)

list(opts)

delete(name, opts)

finni.auto (Module)

explicit_ctx(session, project, opts)

save(opts)

detach(opts)

load(autosession, opts)

`vim.pack`

`lazy.nvim`

`mini.deps`

`finni.pickers.PickerConfig` (Class)

`snacks.picker`

`finni.pickers.snacks` (Module)

setup(`opts`)

manual_picker(`opts`)

auto_all_picker(`opts`)

auto_picker(`opts`, `project_name`)

project_picker(`opts`)

`fzf-lua`

`finni.pickers.fzf_lua` (Module)

setup(`opts`, `register`)

manual_picker(`opts`)

auto_all_picker(`opts`)

auto_picker(`opts`, `project_name`)

project_picker(`opts`)

`mini.pick`

`finni.pickers.mini_pick` (Module)

setup(`opts`, `register`)

manual_picker(`opts`)

auto_all_picker(`opts`)

auto_picker(`opts`, `project_name`)

project_picker(`opts`)

`telescope.nvim`

`finni.pickers.telescope` (Module)

setup(`opts`)

manual_picker(`opts`)

auto_all_picker(`opts`)

auto_picker(`opts`, `project_name`)

project_picker(`opts`)

`autosession`

`extensions`

`load`

`log`

`session`

`finni.session` (Module)

save(`name`, `opts`)

save_tab(`name`, `opts`)

save_all(`opts`)

load(`name`, `opts`)

detach(`target`, `reason`, `opts`)

list(`opts`)

delete(`name`, `opts`)

`finni.auto` (Module)

explicit_ctx(`session`, `project`, `opts`)

save(`opts`)

detach(`opts`)

load(`autosession`, `opts`)

switch(`session`, `project`, `opts`)

start(`cwd`, `opts`)

delete(`session`, `project`, `opts`)

reset(`opts`)

reset_project(`opts`)

list(`opts`)

list_projects(`opts`)

migrate_projects(`opts`)

info(`opts`)

`finni.auto.ActiveAutosessionInfo` (Class)

`finni.auto.AutosessionConfig.ProjectInfo` (Class)

`finni.auto.AutosessionContext` (Class)

`finni.auto.AutosessionSpec.GitInfo` (Class)

`finni.auto.EnabledHook` (Alias)

`finni.auto.ListOpts` (Class)

`finni.auto.ListProjectOpts` (Class)

`finni.auto.LoadOpts` (Alias)

`finni.auto.LoadOptsHook` (Alias)

`finni.auto.MigrateProjectsOpts` (Class)

`finni.auto.ProjectNameHook` (Alias)

`finni.auto.ResetOpts` (Class)

`finni.auto.ResetProjectOpts` (Class)

`finni.auto.SaveOpts` (Alias)

`finni.auto.SessionNameHook` (Alias)

`finni.auto.SpecHook` (Alias)

`finni.auto.WorkspaceHook` (Alias)

`finni.BufFilter` (Alias)

`finni.core.ActiveSession` (Class)

new(`name`, `session_file`, `state_dir`, `context_dir`, `opts`, `tabid`, `needs_restore`)

from_snapshot(`name`, `session_file`, `state_dir`, `context_dir`, `opts`)