226 lines
9.4 KiB
Plaintext
226 lines
9.4 KiB
Plaintext
*mini.sessions* Session management
|
|
*MiniSessions*
|
|
|
|
MIT License Copyright (c) 2021 Evgeni Chasnovski
|
|
|
|
==============================================================================
|
|
|
|
Read, write, and delete sessions. Works using |mksession| (meaning
|
|
'sessionoptions' is fully respected). This is intended as a drop-in Lua
|
|
replacement for session management part of 'mhinz/vim-startify' (works out
|
|
of the box with sessions created by it). Implements both global (from
|
|
configured directory) and local (from current directory) sessions.
|
|
|
|
Key design ideas:
|
|
- Sessions are represented by readable files (results of applying
|
|
|mksession|). There are two kinds of sessions:
|
|
- Global: any file inside a configurable directory.
|
|
- Local: configurable file inside current working directory (|getcwd|).
|
|
|
|
- All session files are detected during `MiniSessions.setup()` and on any
|
|
relevant action with session names being file names (including their
|
|
possible extension).
|
|
|
|
- Store information about detected sessions in separate table
|
|
(|MiniSessions.detected|) and operate only on it. Meaning if this
|
|
information changes, there will be no effect until next detection. So to
|
|
avoid confusion, don't directly use |mksession| and |source| for writing
|
|
and reading sessions files.
|
|
|
|
Features:
|
|
- Autoread default session (local if detected, latest otherwise) if Neovim
|
|
was called without intention to show something else.
|
|
|
|
- Autowrite current session before quitting Neovim.
|
|
|
|
- Configurable severity level of all actions.
|
|
|
|
# Setup ~
|
|
|
|
This module needs a setup with `require('mini.sessions').setup({})`
|
|
(replace `{}` with your `config` table). It will create global Lua table
|
|
`MiniSessions` which you can use for scripting or manually (with
|
|
`:lua MiniSessions.*`).
|
|
|
|
See |MiniSessions.config| for `config` structure and default values.
|
|
|
|
This module doesn't benefit from buffer local configuration, so using
|
|
`vim.b.minisessions_config` will have no effect here.
|
|
|
|
# Disabling ~
|
|
|
|
To disable core functionality, set `vim.g.minisessions_disable` (globally) or
|
|
`vim.b.minisessions_disable` (for a buffer) to `true`. Considering high
|
|
number of different scenarios and customization intentions, writing exact
|
|
rules for disabling module's functionality is left to user. See
|
|
|mini.nvim-disabling-recipes| for common recipes.
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniSessions.setup()*
|
|
`MiniSessions.setup`({config})
|
|
Module setup
|
|
|
|
Parameters ~
|
|
{config} `(table|nil)` Module config table. See |MiniSessions.config|.
|
|
|
|
Usage ~
|
|
>lua
|
|
require('mini.sessions').setup() -- use default config
|
|
-- OR
|
|
require('mini.sessions').setup({}) -- replace {} with your config table
|
|
<
|
|
------------------------------------------------------------------------------
|
|
*MiniSessions.config*
|
|
`MiniSessions.config`
|
|
Module config
|
|
|
|
Default values:
|
|
>lua
|
|
MiniSessions.config = {
|
|
-- Whether to read latest session if Neovim opened without file arguments
|
|
autoread = false,
|
|
|
|
-- Whether to write current session before quitting Neovim
|
|
autowrite = true,
|
|
|
|
-- Directory where global sessions are stored (use `''` to disable)
|
|
directory = --<"session" subdir of user data directory from |stdpath()|>,
|
|
|
|
-- File for local session (use `''` to disable)
|
|
file = 'Session.vim',
|
|
|
|
-- Whether to force possibly harmful actions (meaning depends on function)
|
|
force = { read = false, write = true, delete = false },
|
|
|
|
-- Hook functions for actions. Default `nil` means 'do nothing'.
|
|
-- Takes table with active session data as argument.
|
|
hooks = {
|
|
-- Before successful action
|
|
pre = { read = nil, write = nil, delete = nil },
|
|
-- After successful action
|
|
post = { read = nil, write = nil, delete = nil },
|
|
},
|
|
|
|
-- Whether to print session path after action
|
|
verbose = { read = false, write = true, delete = true },
|
|
}
|
|
<
|
|
------------------------------------------------------------------------------
|
|
*MiniSessions.detected*
|
|
`MiniSessions.detected`
|
|
Table of detected sessions. Keys represent session name. Values are tables
|
|
with session information that currently has these fields (but subject to
|
|
change):
|
|
- <modify_time> `(number)` modification time (see |getftime|) of session file.
|
|
- <name> `(string)` name of session (should be equal to table key).
|
|
- <path> `(string)` full path to session file.
|
|
- <type> `(string)` type of session ('global' or 'local').
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniSessions.read()*
|
|
`MiniSessions.read`({session_name}, {opts})
|
|
Read detected session
|
|
|
|
What it does:
|
|
- If there is an active session, write it with |MiniSessions.write()|.
|
|
- Delete all current buffers with |bwipeout|. This is needed to correctly
|
|
restore buffers from target session. If `force` is not `true`, checks
|
|
beforehand for unsaved listed buffers and stops if there is any.
|
|
- Source session with supplied name.
|
|
|
|
Parameters ~
|
|
{session_name} `(string|nil)` Name of detected session file to read. Default:
|
|
`nil` for default session: local (if detected) or latest session (see
|
|
|MiniSessions.get_latest|).
|
|
{opts} `(table|nil)` Table with options. Current allowed keys:
|
|
- <force> (whether to delete unsaved buffers; default:
|
|
`MiniSessions.config.force.read`).
|
|
- <verbose> (whether to print session path after action; default
|
|
`MiniSessions.config.verbose.read`).
|
|
- <hooks> (a table with <pre> and <post> function hooks to be executed
|
|
with session data argument before and after successful read; overrides
|
|
`MiniSessions.config.hooks.pre.read` and
|
|
`MiniSessions.config.hooks.post.read`).
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniSessions.write()*
|
|
`MiniSessions.write`({session_name}, {opts})
|
|
Write session
|
|
|
|
What it does:
|
|
- Check if file for supplied session name already exists. If it does and
|
|
`force` is not `true`, then stop.
|
|
- Write session with |mksession| to a file named `session_name`. Its
|
|
directory is determined based on type of session:
|
|
- It is at location |v:this_session| if `session_name` is `nil` and
|
|
there is current session.
|
|
- It is current working directory (|getcwd|) if `session_name` is equal
|
|
to `MiniSessions.config.file` (represents local session).
|
|
- It is `MiniSessions.config.directory` otherwise (represents global
|
|
session).
|
|
- Update |MiniSessions.detected|.
|
|
|
|
Parameters ~
|
|
{session_name} `(string|nil)` Name of session file to write. Default: `nil` for
|
|
current session (|v:this_session|).
|
|
{opts} `(table|nil)` Table with options. Current allowed keys:
|
|
- <force> (whether to ignore existence of session file; default:
|
|
`MiniSessions.config.force.write`).
|
|
- <verbose> (whether to print session path after action; default
|
|
`MiniSessions.config.verbose.write`).
|
|
- <hooks> (a table with <pre> and <post> function hooks to be executed
|
|
with session data argument before and after successful write; overrides
|
|
`MiniSessions.config.hooks.pre.write` and
|
|
`MiniSessions.config.hooks.post.write`).
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniSessions.delete()*
|
|
`MiniSessions.delete`({session_name}, {opts})
|
|
Delete detected session
|
|
|
|
What it does:
|
|
- Check if session name is a current one. If yes and `force` is not `true`,
|
|
then stop.
|
|
- Delete session.
|
|
- Update |MiniSessions.detected|.
|
|
|
|
Parameters ~
|
|
{session_name} `(string|nil)` Name of detected session file to delete. Default:
|
|
`nil` for name of current session (taken from |v:this_session|).
|
|
{opts} `(table|nil)` Table with options. Current allowed keys:
|
|
- <force> (whether to allow deletion of current session; default:
|
|
`MiniSessions.config.force.delete`).
|
|
- <verbose> (whether to print session path after action; default
|
|
`MiniSessions.config.verbose.delete`).
|
|
- <hooks> (a table with <pre> and <post> function hooks to be executed
|
|
with session data argument before and after successful delete; overrides
|
|
`MiniSessions.config.hooks.pre.delete` and
|
|
`MiniSessions.config.hooks.post.delete`).
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniSessions.select()*
|
|
`MiniSessions.select`({action}, {opts})
|
|
Select session interactively and perform action
|
|
|
|
Note: this uses |vim.ui.select()| function. For more user-friendly
|
|
experience, override it (for example, with external plugins like
|
|
"stevearc/dressing.nvim").
|
|
|
|
Parameters ~
|
|
{action} `(string|nil)` Action to perform. Should be one of "read" (default),
|
|
"write", or "delete".
|
|
{opts} `(table|nil)` Options for specified action.
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniSessions.get_latest()*
|
|
`MiniSessions.get_latest`()
|
|
Get name of latest detected session
|
|
|
|
Latest session is the session with the latest modification time determined
|
|
by |getftime|.
|
|
|
|
Return ~
|
|
`(string|nil)` Name of latest session or `nil` if there is no sessions.
|
|
|
|
|
|
vim:tw=78:ts=8:noet:ft=help:norl: |