Repository navigation
Expand file tree
/
Copy pathmini-sessions.txt
More file actions
241 lines (196 loc) · 10.3 KB
/
Copy pathmini-sessions.txt
File metadata and controls
241 lines (196 loc) · 10.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
*mini.sessions* Session management
MIT License Copyright (c) 2021 Evgeni Chasnovski
------------------------------------------------------------------------------
*MiniSessions*
Read, write, and delete sessions. Uses |:mksession| (meaning |'sessionoptions'|
is fully respected). This is intended as a drop-in Lua replacement for
[mhinz/vim-startify](https://github.com/mhinz/vim-startify) session management
(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 during
relevant actions (`read`, `delete`, `select`) with file names as session
names (including possible extension).
- No automated new session creation. Use |MiniSessions.write()| manually.
- 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. To avoid confusion,
don't directly use |:mksession| / |:source| for writing / reading session files.
Features:
- Autoread default session (local if detected, else latest written global) if
Neovim was called without intention to show something else.
- Autowrite currently read session before leaving it (quit Neovim or read
another session).
- Restart Neovim preserving current session (requires Neovim>=0.12).
- 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`
Defaults ~
>lua
MiniSessions.config = {
-- Whether to read default session if Neovim opened without file arguments
autoread = false,
-- Whether to write currently read session before leaving it
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 and `autowrite` is `true` in |MiniSessions.config|,
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 are 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 currently read 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
currently read 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 currently read 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.restart()*
`MiniSessions.restart`()
Restart Neovim preserving current session
Write (active or new temporary) session, |:restart| without preserving
a session, source the session.
On Neovim>=0.12.5 consider using |:restart| directly.
Notes:
- Requires Neovim>=0.12 for |:restart| command.
- If there is no active session (|v:this_session|), |argument-list| is cleared
for temporary session to not preserve it.
------------------------------------------------------------------------------
*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, see |MiniPick.ui_select()|).
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: