bryan
/
persisted.nvim
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor!: #145 restore simplicity to the plugin 

Announcement in #145
main
Oli 2024-08-08 18:25:16 +01:00 committed by GitHub
parent 0446fd0217
commit 22e17b07fb
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
14 changed files with 591 additions and 1139 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

211
README.md
View File

@ -23,8 +23,8 @@
## :sparkles: Features
- :evergreen_tree: Supports sessions across multiple git branches
- :telescope: Telescope extension to work with saved sessions
- :tickets: Custom events which users can hook into for tighter integration
- :telescope: Telescope extension to manage sessions
- :tickets: Custom events which users can hook into for tighter integrations
- :memo: Simple API to save/stop/restore/delete/list the current session(s)
- :open_file_folder: Supports autosaving and autoloading of sessions with allowed/ignored directories
- :floppy_disk: Automatically saves the active session under `.local/share/nvim/sessions` on exiting Neovim
@ -35,7 +35,7 @@
## :package: Installation
Install the plugin with your preferred package manager:
Install and configure the plugin with your preferred package manager:
**[Lazy.nvim](https://github.com/folke/lazy.nvim)**
@ -110,7 +110,7 @@ require('telescope').setup({
The plugin comes with a number of commands:
- `:SessionToggle` - Determines whether to load, start or stop a session
- `:SessionStart` - Start recording a session. Useful if `autosave = false`
- `:SessionStart` - Start recording a session. Useful if `autostart = false`
- `:SessionStop` - Stop recording a session
- `:SessionSave` - Save the current session
- `:SessionLoad` - Load the session for the current directory and current branch (if `git_use_branch = true`)
@ -123,12 +123,12 @@ The plugin comes with a number of commands:
<!-- panvimdoc-ignore-start -->
<p align="center">
<img src="https://github.com/olimorris/persisted.nvim/assets/9512444/5bfd6f94-ff70-4f2b-9193-53cdf7140d75" alt="Telescope">
<img src="https://github.com/user-attachments/assets/3ff91790-b61a-4089-b87d-432e8b4969c2" alt="Telescope">
</p>
<!-- panvimdoc-ignore-end -->
The Telescope extension may be opened via `:Telescope persisted`. The available actions are:
The Telescope extension may be opened via `:Telescope persisted`. The default actions are:
- `<CR>` - Open/source the session file
- `<C-b>` - Add/update the git branch for the session file
@ -140,8 +140,8 @@ The Telescope extension may be opened via `:Telescope persisted`. The available
The plugin sets a number of global variables throughout its lifecycle:
- `vim.g.persisting` - (bool) Determines if the plugin is active for the current session
- `vim.g.persisted_exists` - (bool) Determines if a session exists for the current working directory
- `vim.g.persisted_loaded_session` - (string) The file path to the current session
- `vim.g.persisting_session` - (string) The file path to the current session (if `follow_cwd` is false)
- `vim.g.persisted_loaded_session` - (string) The file path to the last loaded session
## :wrench: Configuration
@ -150,34 +150,41 @@ The plugin sets a number of global variables throughout its lifecycle:
The plugin comes with the following defaults:
```lua
require("persisted").setup({
log_level = "ERROR", -- One of "TRACE", "DEBUG", "ERROR"
save_dir = vim.fn.expand(vim.fn.stdpath("data") .. "/sessions/"), -- directory where session files are saved
silent = false, -- silent nvim message when sourcing session file
use_git_branch = false, -- create session files based on the branch of a git enabled repository
default_branch = "main", -- the branch to load if a session file is not found for the current branch
autosave = true, -- automatically save session files when exiting Neovim
should_autosave = nil, -- function to determine if a session should be autosaved
autoload = false, -- automatically load the session for the cwd on Neovim startup
on_autoload_no_session = nil, -- function to run when `autoload = true` but there is no session to load
follow_cwd = true, -- change session file name to match current working directory if it changes
allowed_dirs = nil, -- table of dirs that the plugin will auto-save and auto-load from
ignored_dirs = nil, -- table of dirs that are ignored when auto-saving and auto-loading
ignored_branches = nil, -- table of branch patterns that are ignored for auto-saving and auto-loading
{
autostart = true, -- Automatically start the plugin on load?
-- Function to determine if a session should be saved
---@type fun(): boolean
should_save = function()
return true
end,
save_dir = vim.fn.expand(vim.fn.stdpath("data") .. "/sessions/"), -- Directory where session files are saved
follow_cwd = true, -- Change the session file to match any change in the cwd?
use_git_branch = false, -- Include the git branch in the session file name?
autoload = false, -- Automatically load the session for the cwd on Neovim startup?
-- Function to run when `autoload = true` but there is no session to load
---@type fun(): any
on_autoload_no_session = function() end,
allowed_dirs = {}, -- Table of dirs that the plugin will start and autoload from
ignored_dirs = {}, -- Table of dirs that are ignored for starting and autoloading
telescope = {
reset_prompt = true, -- Reset the Telescope prompt after an action?
mappings = { -- table of mappings for the Telescope extension
change_branch = "<c-b>",
copy_session = "<c-c>",
delete_session = "<c-d>",
mappings = { -- Mappings for managing sessions in Telescope
copy_session = "<C-c>",
change_branch = "<C-b>",
delete_session = "<C-d>",
},
icons = { -- icons displayed in the picker, set to nil to disable entirely
icons = { -- icons displayed in the Telescope picker
selected = " ",
dir = " ",
branch = " ",
dir = " ",
selected = " ",
},
},
})
}
```
**What is saved in the session?**
@ -185,7 +192,7 @@ require("persisted").setup({
As the plugin uses Vim's `:mksession` command then you may change the `vim.o.sessionoptions` value to determine what to write into the session. Please see `:h sessionoptions` for more information.
> [!NOTE]
> The author uses: `vim.o.sessionoptions = "buffers,curdir,folds,tabpages,winpos,winsize"`
> The author uses: `vim.o.sessionoptions = "buffers,curdir,folds,globals,tabpages,winpos,winsize"`
**Session save location**
@ -210,24 +217,27 @@ require("persisted").setup({
})
```
**Autosaving**
**Autostart**
By default, the plugin will automatically save a Neovim session to disk when the `VimLeavePre` event is triggered. Autosaving can be turned off by:
By default, the plugin will automatically start when the setup function is called. This results in a Neovim session being saved to disk when the `VimLeavePre` event is triggered. This can be disabled by:
```lua
require("persisted").setup({
autosave = false,
autostart = false,
})
```
Autosaving can be further controlled for certain directories by specifying `allowed_dirs` and `ignored_dirs`.
Autostarting can be further controlled for certain directories by specifying `allowed_dirs` and `ignored_dirs`.
There may be occasions when you do not wish to autosave; perhaps when a dashboard or a certain buftype is present. To control this, a callback function, `should_autosave`, may be used which should return a boolean value.
**`should_save`**
There may be occasions when you do not wish to save the session; perhaps when a dashboard or a certain filetype is present. To handle this, the `should_save` function may be used which should return a boolean value.
```lua
require("persisted").setup({
should_autosave = function()
-- do not autosave if the alpha dashboard is the current filetype
---@return bool
should_save = function()
-- Do not save if the alpha dashboard is the current filetype
if vim.bo.filetype == "alpha" then
return false
end
@ -236,10 +246,7 @@ require("persisted").setup({
})
```
Of course, if you wish to manually save the session when autosaving is disabled, the `:SessionSave` command can be used.
> [!NOTE]
> If `autosave = false` then the `should_autosave` callback will not be executed.
Of course, if you wish to manually save the session the `:SessionSave` command can be used.
**Autoloading**
@ -251,7 +258,7 @@ require("persisted").setup({
})
```
You can also provide a function to run when `autoload = true` but there is no session to be loaded:
You can also provide a function to run when `autoload = true` and there is no session to load:
```lua
require("persisted").setup({
@ -262,29 +269,14 @@ require("persisted").setup({
})
```
Autoloading can be further controlled for certain directories by specifying `allowed_dirs` and `ignored_dirs`.
Autoloading can be further controlled for directories in the `allowed_dirs` and `ignored_dirs` config tables.
> [!NOTE]
> Autoloading will not occur if the plugin is lazy loaded or a user opens Neovim with arguments other than a single directory argument. For example: `nvim some_file.rb` will not result in autoloading but `nvim some/existing/path` or `nvim .` will.
**Following current working directory**
There may be a need to change the working directory to quickly access files in other directories without changing the current session's name on save. This behavior can be configured with `follow_cwd = false`.
By default, the session name will match the current working directory:
```lua
require("persisted").setup({
follow_cwd = true,
})
```
> [!NOTE]
> If `follow_cwd = false` the session name is stored upon loading under the global variable `vim.g.persisting_session`. This variable can be manually adjusted if changes to the session name are needed. Alternatively, if `follow_cwd = true` then `vim.g.persisting_session = nil`.
> [!IMPORTANT]
> By design, the plugin will not autoload a session when any arguments are passed to Neovim such as `nvim my_file.py`
**Allowed directories**
You may specify a table of directories for which the plugin will autosave and/or autoload from. For example:
You may specify a table of directories for which the plugin will start and/or autoload from. For example:
```lua
require("persisted").setup({
@ -295,14 +287,14 @@ require("persisted").setup({
})
```
Specifying `~/Code` will autosave and autoload from that directory as well as all its sub-directories.
Specifying `~/Code` will start and autoload from that directory as well as all its sub-directories.
> [!NOTE]
> If `allowed_dirs` is left at its default value and `autosave` and/or `autoload` are set to `true`, then the plugin will autoload/autosave from _any_ directory
> If `allowed_dirs` is left at its default value and `autostart` and/or `autoload` are set to `true`, then the plugin will start and autoload from _any_ directory
**Ignored directories**
You may specify a table of directories for which the plugin will **never** autosave and autoload from. For example:
You may specify a table of directories for which the plugin will **never** start and autoload from. For example:
```lua
require("persisted").setup({
@ -330,19 +322,6 @@ require("persisted").setup({
In this setup, `~/.config` and `~/.local/nvim` are still going to behave in their default setting (ignoring all listed directory and its children), however `/` and `/tmp` will only ignore those directories exactly.
**Ignored branches**
You may specify a table of patterns that match against branches for which the plugin will **never** autosave and autoload from:
```lua
require("persisted").setup({
ignored_branches = {
"^master",
"feature/%u"
},
})
```
**Events / Callbacks**
The plugin fires events at various points during its lifecycle:
@ -355,21 +334,19 @@ The plugin fires events at various points during its lifecycle:
- `PersistedSavePost` - For _after_ a session is saved
- `PersistedDeletePre` - For _before_ a session is deleted
- `PersistedDeletePost` - For _after_ a session is deleted
- `PersistedStateChange` - For when a session is _started_ or _stopped_
- `PersistedToggled` - For when a session is toggled
- `PersistedStart` - For when a session has _started_
- `PersistedStop` - For when a session has _stopped_
- `PersistedToggle` - For when a session is toggled
These events can be consumed anywhere within your configuration by utilising the `vim.api.nvim_create_autocmd` function.
A commonly requested example is to use the Telescope extension to load a session, saving the current session before clearing all of the open buffers:
```lua
local group = vim.api.nvim_create_augroup("PersistedHooks", {})
vim.api.nvim_create_autocmd({ "User" }, {
vim.api.nvim_create_autocmd("User", {
pattern = "PersistedTelescopeLoadPre",
group = group,
callback = function(session)
-- Save the currently loaded session using a global variable
-- Save the currently loaded session using the global variable
require("persisted").save({ session = vim.g.persisted_loaded_session })
-- Delete all of the open buffers
@ -378,33 +355,59 @@ vim.api.nvim_create_autocmd({ "User" }, {
})
```
**Using callback data**
**Highlights**
When certain events are fired, session data is made available for the user to consume, for example:
The plugin also comes with pre-defined highlight groups for the Telescope implementation:
- `PersistedTelescopeSelected`
- `PersistedTelescopeDir`
- `PersistedTelescopeBranch`
## :building_construction: Extending the Plugin
The plugin has been designed to be fully extensible. All of the functions in the [init.lua](https://github.com/olimorris/persisted.nvim/blob/main/lua/persisted/init.lua) and [utils.lua](https://github.com/olimorris/persisted.nvim/blob/main/lua/persisted/utils.lua) file are public.
Consider a user who wishes to autoload a session if arguments are passed to Neovim. A custom autocmd can be created which forces the autoload:
```lua
{
branch = "main",
dir_path = "Code/Neovim/persisted.nvim",
file_path = "/Users/Oli/.local/share/nvim/sessions/%Users%Oli%Code%Neovim%persisted.nvim@@main.vim",
name = "Code/Neovim/persisted.nvim@@main",
}
```
local persisted = require("persisted")
To consume this data, use the `session.data` table in your autocmd:
persisted.setup({
autoload = true
})
```lua
vim.api.nvim_create_autocmd({ "User" }, {
pattern = "PersistedLoadPost",
group = group,
callback = function(session)
print(session.data.branch)
vim.api.nvim_create_autocmd("VimEnter", {
nested = true,
callback = function()
-- Add more complex logic here
if vim.fn.argc() > 0 then
-- Leverage the plugin's ability to resolve allowed_dirs and ignored_dirs
require("persisted").autoload({ force = true })
end
end,
})
```
> [!NOTE]
> This data is available for the `PersistedLoad`, `PersistedDelete` and `PersistedTelescope` events
Or, a user who wishes to check whether the current branch is in a table of branches to be ignored:
```lua
local persisted = require("persisted")
local utils = require("persisted.utils")
persisted.setup({
autostart = false,
use_git_branch = true,
})
local ignored_branches = {
"feature_branch"
}
if utils.in_table(persisted.branch(), ignored_branches) ~= nil then
persisted.load()
persisted.start()
end
```
## :page_with_curl: License

261
doc/persisted.nvim.txt
View File

@ -8,14 +8,14 @@ Table of Contents *persisted.nvim-table-of-contents*
- Installation |persisted.nvim-installation|
- Usage |persisted.nvim-usage|
- Configuration |persisted.nvim-configuration|
- Extending the Plugin |persisted.nvim-extending-the-plugin|
- License |persisted.nvim-license|
FEATURES *persisted.nvim-features*
- Supports sessions across multiple git branches
- Telescope extension to work with saved sessions
- Custom events which users can hook into for tighter integration
- Telescope extension to manage sessions
- Custom events which users can hook into for tighter integrations
- Simple API to save/stop/restore/delete/list the current session(s)
- Supports autosaving and autoloading of sessions with allowed/ignored directories
- Automatically saves the active session under `.local/share/nvim/sessions` on exiting Neovim
@ -23,7 +23,6 @@ FEATURES *persisted.nvim-features*
REQUIREMENTS *persisted.nvim-requirements*
- Neovim >= 0.8.0
@ -106,9 +105,8 @@ USAGE *persisted.nvim-usage*
The plugin comes with a number of commands:
- `:SessionToggle` - Determines whether to load, start or stop a session
- `:SessionStart` - Start recording a session. Useful if `autosave = false`
- `:SessionStart` - Start recording a session. Useful if `autostart = false`
- `:SessionStop` - Stop recording a session
- `:SessionSave` - Save the current session
- `:SessionLoad` - Load the session for the current directory and current branch (if `git_use_branch = true`)
@ -118,10 +116,9 @@ The plugin comes with a number of commands:
**Telescope extension**
The Telescope extension may be opened via `:Telescope persisted`. The available
The Telescope extension may be opened via `:Telescope persisted`. The default
actions are:
- `<CR>` - Open/source the session file
- `<C-b>` - Add/update the git branch for the session file
- `<C-c>` - Copy the session file
@ -131,10 +128,9 @@ actions are:
The plugin sets a number of global variables throughout its lifecycle:
- `vim.g.persisting` - (bool) Determines if the plugin is active for the current session
- `vim.g.persisted_exists` - (bool) Determines if a session exists for the current working directory
- `vim.g.persisted_loaded_session` - (string) The file path to the current session
- `vim.g.persisting_session` - (string) The file path to the current session (if `follow_cwd` is false)
- `vim.g.persisted_loaded_session` - (string) The file path to the last loaded session
CONFIGURATION *persisted.nvim-configuration*
@ -144,45 +140,53 @@ CONFIGURATION *persisted.nvim-configuration*
The plugin comes with the following defaults:
>lua
require("persisted").setup({
log_level = "ERROR", -- One of "TRACE", "DEBUG", "ERROR"
save_dir = vim.fn.expand(vim.fn.stdpath("data") .. "/sessions/"), -- directory where session files are saved
silent = false, -- silent nvim message when sourcing session file
use_git_branch = false, -- create session files based on the branch of a git enabled repository
default_branch = "main", -- the branch to load if a session file is not found for the current branch
autosave = true, -- automatically save session files when exiting Neovim
should_autosave = nil, -- function to determine if a session should be autosaved
autoload = false, -- automatically load the session for the cwd on Neovim startup
on_autoload_no_session = nil, -- function to run when `autoload = true` but there is no session to load
follow_cwd = true, -- change session file name to match current working directory if it changes
allowed_dirs = nil, -- table of dirs that the plugin will auto-save and auto-load from
ignored_dirs = nil, -- table of dirs that are ignored when auto-saving and auto-loading
ignored_branches = nil, -- table of branch patterns that are ignored for auto-saving and auto-loading
{
---@type boolean
autostart = true, -- Automatically start the plugin on load?
---@type fun(boolean)
should_save = nil, -- Function to determine if a session should be saved
---@type string
save_dir = vim.fn.expand(vim.fn.stdpath("data") .. "/sessions/"), -- Directory where session files are saved
---@type boolean
use_git_branch = false, -- Include the git branch in the session file name?
---@type boolean
autoload = false, -- Automatically load the session for the cwd on Neovim startup?
---@type fun(boolean)
on_autoload_no_session = nil, -- Function to run when `autoload = true` but there is no session to load
---@type boolean
follow_cwd = true, -- Change session file name with changes in the cwd?
---@type table
allowed_dirs = nil, -- Table of dirs that the plugin will start and autoload from
---@type table
ignored_dirs = nil, -- Table of dirs that are ignored for autosaving and autoloading
telescope = {
reset_prompt = true, -- Reset the Telescope prompt after an action?
mappings = { -- table of mappings for the Telescope extension
change_branch = "<c-b>",
copy_session = "<c-c>",
delete_session = "<c-d>",
mappings = { -- Mappings for managing sessions in Telescope
change_branch = "<C-b>",
copy_session = "<C-c>",
delete_session = "<C-d>",
},
icons = { -- icons displayed in the picker, set to nil to disable entirely
branch = " ",
dir = " ",
selected = " ",
icons = { -- icons displayed in the Telescope picker
selected = " ",
dir = " ",
branch = " ",
},
},
})
}
<
**What is saved in the session?**
As the plugin uses Vim’s `:mksession` command then you may change the
`vim.o.sessionoptions` value to determine what to write into the session.
Please see `:h sessionoptions` for more information.
Please see |sessionoptions| for more information.
[!NOTE] The author uses: `vim.o.sessionoptions =
"buffers,curdir,folds,tabpages,winpos,winsize"`
"buffers,curdir,folds,globals,tabpages,winpos,winsize"`
**Session save location**
The location of the session files may be changed by altering the `save_dir`
@ -208,28 +212,32 @@ files for a given project, by using git branches. To enable git branching:
})
<
**Autosaving**
**Autostart**
By default, the plugin will automatically save a Neovim session to disk when
the `VimLeavePre` event is triggered. Autosaving can be turned off by:
By default, the plugin will automatically start when the setup function is
called. This results in a Neovim session being saved to disk when the
`VimLeavePre` event is triggered. This can be disabled by:
>lua
require("persisted").setup({
autosave = false,
autostart = false,
})
<
Autosaving can be further controlled for certain directories by specifying
Autostarting can be further controlled for certain directories by specifying
`allowed_dirs` and `ignored_dirs`.
There may be occasions when you do not wish to autosave; perhaps when a
dashboard or a certain buftype is present. To control this, a callback
function, `should_autosave`, may be used which should return a boolean value.
**should_save**
There may be occasions when you do not wish to save the session; perhaps when a
dashboard or a certain filetype is present. To handle this, the `should_save`
function may be used which should return a boolean value.
>lua
require("persisted").setup({
should_autosave = function()
-- do not autosave if the alpha dashboard is the current filetype
---@return bool
should_save = function()
-- Do not save if the alpha dashboard is the current filetype
if vim.bo.filetype == "alpha" then
return false
end
@ -238,12 +246,9 @@ function, `should_autosave`, may be used which should return a boolean value.
})
<
Of course, if you wish to manually save the session when autosaving is
disabled, the `:SessionSave` command can be used.
Of course, if you wish to manually save the session the `:SessionSave` command
can be used.
[!NOTE] If `autosave = false` then the `should_autosave` callback will not be
executed.
**Autoloading**
The plugin can be enabled to automatically load sessions when Neovim is
@ -255,8 +260,8 @@ started. Whilst off by default, this can be turned on by:
})
<
You can also provide a function to run when `autoload = true` but there is no
session to be loaded:
You can also provide a function to run when `autoload = true` and there is no
session to load:
>lua
require("persisted").setup({
@ -267,37 +272,16 @@ session to be loaded:
})
<
Autoloading can be further controlled for certain directories by specifying
`allowed_dirs` and `ignored_dirs`.
Autoloading can be further controlled for directories in the `allowed_dirs` and
`ignored_dirs` config tables.
[!NOTE] Autoloading will not occur if the plugin is lazy loaded or a user opens
Neovim with arguments other than a single directory argument. For example:
`nvim some_file.rb` will not result in autoloading but `nvim
some/existing/path` or `nvim .` will.
**Following current working directory**
There may be a need to change the working directory to quickly access files in
other directories without changing the current session’s name on save. This
behavior can be configured with `follow_cwd = false`.
By default, the session name will match the current working directory:
>lua
require("persisted").setup({
follow_cwd = true,
})
<
[!NOTE] If `follow_cwd = false` the session name is stored upon loading under
the global variable `vim.g.persisting_session`. This variable can be manually
adjusted if changes to the session name are needed. Alternatively, if
`follow_cwd = true` then `vim.g.persisting_session = nil`.
[!IMPORTANT] By design, the plugin will not autoload a session when any
arguments are passed to Neovim such as `nvim my_file.py`
**Allowed directories**
You may specify a table of directories for which the plugin will autosave
and/or autoload from. For example:
You may specify a table of directories for which the plugin will start and/or
autoload from. For example:
>lua
require("persisted").setup({
@ -308,17 +292,17 @@ and/or autoload from. For example:
})
<
Specifying `~/Code` will autosave and autoload from that directory as well as
all its sub-directories.
Specifying `~/Code` will start and autoload from that directory as well as all
its sub-directories.
[!NOTE] If `allowed_dirs` is left at its default value and `autosave` and/or
`autoload` are set to `true`, then the plugin will autoload/autosave from _any_
directory
[!NOTE] If `allowed_dirs` is left at its default value and `autostart` and/or
`autoload` are set to `true`, then the plugin will start and autoload from
_any_ directory
**Ignored directories**
You may specify a table of directories for which the plugin will **never**
autosave and autoload from. For example:
start and autoload from. For example:
>lua
require("persisted").setup({
@ -351,25 +335,10 @@ In this setup, `~/.config` and `~/.local/nvim` are still going to behave in
their default setting (ignoring all listed directory and its children), however
`/` and `/tmp` will only ignore those directories exactly.
**Ignored branches**
You may specify a table of patterns that match against branches for which the
plugin will **never** autosave and autoload from:
>lua
require("persisted").setup({
ignored_branches = {
"^master",
"feature/%u"
},
})
<
**Events / Callbacks**
The plugin fires events at various points during its lifecycle:
- `PersistedLoadPre` - For _before_ a session is loaded
- `PersistedLoadPost` - For _after_ a session is loaded
- `PersistedTelescopeLoadPre` - For _before_ a session is loaded via Telescope
@ -378,8 +347,9 @@ The plugin fires events at various points during its lifecycle:
- `PersistedSavePost` - For _after_ a session is saved
- `PersistedDeletePre` - For _before_ a session is deleted
- `PersistedDeletePost` - For _after_ a session is deleted
- `PersistedStateChange` - For when a session is _started_ or _stopped_
- `PersistedToggled` - For when a session is toggled
- `PersistedStart` - For when a session has _started_
- `PersistedStop` - For when a session has _stopped_
- `PersistedToggle` - For when a session is toggled
These events can be consumed anywhere within your configuration by utilising
the `vim.api.nvim_create_autocmd` function.
@ -388,13 +358,10 @@ A commonly requested example is to use the Telescope extension to load a
session, saving the current session before clearing all of the open buffers:
>lua
local group = vim.api.nvim_create_augroup("PersistedHooks", {})
vim.api.nvim_create_autocmd({ "User" }, {
vim.api.nvim_create_autocmd("User", {
pattern = "PersistedTelescopeLoadPre",
group = group,
callback = function(session)
-- Save the currently loaded session using a global variable
-- Save the currently loaded session using the global variable
require("persisted").save({ session = vim.g.persisted_loaded_session })
-- Delete all of the open buffers
@ -403,35 +370,69 @@ session, saving the current session before clearing all of the open buffers:
})
<
**Using callback data**
**Highlights**
When certain events are fired, session data is made available for the user to
consume, for example:
The plugin also comes with pre-defined highlight groups for the Telescope
implementation:
- `PersistedTelescopeSelected`
- `PersistedTelescopeDir`
- `PersistedTelescopeBranch`
EXTENDING THE PLUGIN *persisted.nvim-extending-the-plugin*
The plugin has been designed to be fully extensible. All of the functions in
the init.lua
<https://github.com/olimorris/persisted.nvim/blob/main/lua/persisted/init.lua>
and utils.lua
<https://github.com/olimorris/persisted.nvim/blob/main/lua/persisted/utils.lua>
file are public.
Consider a user who wishes to autoload a session if arguments are passed to
Neovim. A custom autocmd can be created which forces the autoload:
>lua
{
branch = "main",
dir_path = "Code/Neovim/persisted.nvim",
file_path = "/Users/Oli/.local/share/nvim/sessions/%Users%Oli%Code%Neovim%persisted.nvim@@main.vim",
name = "Code/Neovim/persisted.nvim@@main",
}
<
To consume this data, use the `session.data` table in your autocmd:
>lua
vim.api.nvim_create_autocmd({ "User" }, {
pattern = "PersistedLoadPost",
group = group,
callback = function(session)
print(session.data.branch)
local persisted = require("persisted")
persisted.setup({
autoload = true
})
vim.api.nvim_create_autocmd("VimEnter", {
nested = true,
callback = function()
-- Add more complex logic here
if vim.fn.argc() > 0 then
-- Leverage the plugin's ability to resolve allowed_dirs and ignored_dirs
require("persisted").autoload({ force = true })
end
end,
})
<
Or, a user who wishes to check whether the current branch is in an a table of
branches to be ignored:
>lua
local persisted = require("persisted")
local utils = require("persisted.utils")
persisted.setup({
autostart = false,
use_git_branch = true,
})
local ignored_branches = {
"feature_branch"
}
if utils.in_table(persisted.branch(), ignored_branches) ~= nil then
persisted.load()
persisted.start()
end
<
[!NOTE] This data is available for the `PersistedLoad`, `PersistedDelete` and
`PersistedTelescope` events
LICENSE *persisted.nvim-license*

57
lua/persisted/config.lua
View File

@ -1,46 +1,35 @@
local M = {}
return {
autostart = true, -- Automatically start the plugin on load?
local defaults = {
log_level = "ERROR", -- One of "TRACE", "DEBUG", "ERROR"
save_dir = vim.fn.expand(vim.fn.stdpath("data") .. "/sessions/"), -- directory where session files are saved
silent = false, -- silent nvim message when sourcing session file
-- Function to determine if a session should be saved
---@type fun(): boolean
should_save = function()
return true
end,
use_git_branch = false, -- create session files based on the branch of a git enabled repository
branch_separator = "@@", -- string used to separate session directory name from branch name
default_branch = "main", -- the branch to load if a session file is not found for the current branch
save_dir = vim.fn.expand(vim.fn.stdpath("data") .. "/sessions/"), -- Directory where session files are saved
autosave = true, -- automatically save session files when exiting Neovim
should_autosave = nil, -- function to determine if a session should be autosaved (resolve to a boolean)
follow_cwd = true, -- Change the session file to match any change in the cwd?
use_git_branch = false, -- Include the git branch in the session file name?
autoload = false, -- Automatically load the session for the cwd on Neovim startup?
autoload = false, -- automatically load the session for the cwd on Neovim startup
on_autoload_no_session = nil, -- function to run when `autoload = true` but there is no session to load
-- Function to run when `autoload = true` but there is no session to load
---@type fun(): any
on_autoload_no_session = function() end,
follow_cwd = true, -- change session file name with changes in current working directory
allowed_dirs = nil, -- table of dirs that the plugin will auto-save and auto-load from
ignored_dirs = nil, -- table of dirs that are ignored for auto-saving and auto-loading
ignored_branches = nil, -- table of branch patterns that are ignored for auto-saving and auto-loading
allowed_dirs = {}, -- Table of dirs that the plugin will start and autoload from
ignored_dirs = {}, -- Table of dirs that are ignored for starting and autoloading
telescope = {
reset_prompt = true, -- Reset prompt after a telescope action?
--TODO: We should add a deprecation notice for the old API here
mappings = {
change_branch = "<c-b>",
copy_session = "<c-c>",
delete_session = "<c-d>",
mappings = { -- Mappings for managing sessions in Telescope
copy_session = "<C-c>",
change_branch = "<C-b>",
delete_session = "<C-d>",
},
icons = { -- icons displayed in the picker
icons = { -- icons displayed in the Telescope picker
selected = "",
dir = "",
branch = "",
dir = "",
selected = "",
},
},
}
M.options = {}
function M.setup(opts)
M.options = vim.tbl_deep_extend("force", defaults, opts or {})
vim.fn.mkdir(M.options.save_dir, "p")
end
return M

38
lua/persisted/deprecate.lua
View File

@ -1,38 +0,0 @@
---[[
--Courtesy of the awesome work in Nightfox.nvim
--https://github.com/EdenEast/nightfox.nvim/blob/main/lua/nightfox/lib/deprecation.lua
--]
local M = {
_list = { { "[Persisted.nvim]\n", "Question" }, { "The following have been " }, { "deprecated:\n", "WarningMsg" } },
_has_registered = false,
}
function M.write(...)
for _, e in ipairs({ ... }) do
table.insert(M._list, type(e) == "string" and { e } or e)
end
M._list[#M._list][1] = M._list[#M._list][1] .. "\n"
if not M._has_registered then
vim.cmd([[
augroup PersistedDeprecations
au!
autocmd VimEnter * ++once lua require("persisted.deprecate").flush()
augroup END
]])
M._has_registered = true
end
end
function M.flush()
M.write(
"----------\n",
"See ",
{ "https://github.com/olimorris/persisted.nvim/issues/51", "Title" },
" for more information."
)
vim.api.nvim_echo(M._list, true, {})
end
return M

546
lua/persisted/init.lua
View File

@ -1,410 +1,216 @@
local config = require("persisted.config")
local log = require("persisted.log")
local utils = require("persisted.utils")
local uv = vim.uv or vim.loop
local M = {}
local config
local e = vim.fn.fnameescape
local uv = vim.uv or vim.loop
---Escapes special characters before performing string substitution
---@param str string
---@param pattern string
---@param replace string
---@param n? integer
---@return string
---@return integer
local function escape_pattern(str, pattern, replace, n)
pattern = string.gsub(pattern, "[%(%)%.%+%-%*%?%[%]%^%$%%]", "%%%1") -- escape pattern
replace = string.gsub(replace, "[%%]", "%%%%") -- escape replacement
return string.gsub(str, pattern, replace, n)
---Fire an event
---@param event string
function M.fire(event)
vim.api.nvim_exec_autocmds("User", { pattern = "Persisted" .. event })
end
---Gets the directory from the file/path argument passed to Neovim if there's
---exactly one and it resolves to a valid directory
---@return string|nil
local function args_path()
if vim.fn.argc() ~= 1 then
return nil
---Get the current session for the cwd and git branch
---@param opts? {branch?: boolean}
---@return string
function M.current(opts)
opts = opts or {}
local name = vim.fn.getcwd():gsub("[\\/:]+", "%%")
if config.use_git_branch and opts.branch ~= false then
local branch = M.branch()
if branch then
name = name .. "@@" .. branch:gsub("[\\/:]+", "%%")
end
end
-- Use expand() to resolve '~' and use fs_realpath to resolve both '.' and
-- relative paths passed as arguments. Note that argv() will only ever return
-- paths/files passed as arguments and does not include other
-- parameters/arguments. fs_realpath() returns nil if the path doesn't exist.
-- Use isdirectory to validate it's a directory and not a file.
local dir = uv.fs_realpath(vim.fn.expand(vim.fn.argv(0)))
if dir ~= nil and vim.fn.isdirectory(dir) ~= 0 then
return dir
return config.save_dir .. name .. ".vim"
end
---Automatically load the session for the current dir
---@param opts? { force?: boolean }
function M.autoload(opts)
opts = opts or {}
if not opts.force and (vim.fn.argc() > 0 or vim.g.started_with_stdin) then
return
end
if config.autoload and M.allowed_dir() then
M.load({ autoload = true })
end
return nil
end
---Check any arguments passed to Neovim and verify if they're a directory
---Load a session
---@param opts? { last?: boolean, autoload?: boolean, session?: string }
function M.load(opts)
opts = opts or {}
local session
if opts.last then
session = M.last()
elseif opts.session then
session = opts.session
else
session = M.current()
if vim.fn.filereadable(session) == 0 then
session = M.current({ branch = false })
end
end
if session and vim.fn.filereadable(session) ~= 0 then
vim.g.persisting_session = not config.follow_cwd and session or nil
vim.g.persisted_loaded_session = session
M.fire("LoadPre")
vim.cmd("silent! source " .. e(session))
M.fire("LoadPost")
elseif opts.autoload and type(config.on_autoload_no_session) == "function" then
config.on_autoload_no_session()
end
if config.autostart and M.allowed_dir() then
M.start()
end
end
---Start a session
function M.start()
vim.api.nvim_create_autocmd("VimLeavePre", {
group = vim.api.nvim_create_augroup("Persisted", { clear = true }),
callback = function()
M.save()
end,
})
vim.g.persisting = true
M.fire("Start")
end
---Stop a session
function M.stop()
vim.g.persisting = false
pcall(vim.api.nvim_del_augroup_by_name, "Persisted")
M.fire("Stop")
end
---Save the session
---@param opts? { force?: boolean, session?: string }
function M.save(opts)
opts = opts or {}
-- Do not save the session if should_save evals to false...unless it's forced
if type(config.should_save) == "function" and not config.should_save() and not opts.force then
return
end
M.fire("SavePre")
vim.cmd("mks! " .. e(opts.session or vim.g.persisting_session or M.current()))
vim.cmd("sleep 10m")
M.fire("SavePost")
end
---Delete the current session
---@param opts? { session?: string }
function M.delete(opts)
opts = opts or {}
local session = opts.session or M.current()
if session and uv.fs_stat(session) ~= 0 then
M.fire("DeletePre")
vim.schedule(function()
M.stop()
vim.fn.system("rm " .. e(session))
end)
M.fire("DeletePost")
end
end
---Get the current Git branch
---@return string?
function M.branch()
if uv.fs_stat(".git") then
local branch = vim.fn.systemlist("git branch --show-current")[1]
return vim.v.shell_error == 0 and branch or nil
end
end
---Determines whether to load, start or stop a session
function M.toggle()
M.fire("Toggle")
if vim.g.persisting == nil then
return M.load()
end
if vim.g.persisting then
return M.stop()
end
return M.start()
end
---Allow autosaving and autoloading for the given dir?
---@param opts? {dir?: string}
---@return boolean
local function args_check()
-- Args are valid if a single directory was resolved or if no args were used.
return args_path() ~= nil or vim.fn.argc() == 0
end
---Get the directory to be used for the session
---@return string
local function session_dir()
-- Use specified directory from arguments or the working directory otherwise.
return args_path() or vim.fn.getcwd()
end
---Does the current working directory allow for the auto-saving and loading?
---@param dir string Directory to be used for the session
---@return boolean
local function allow_dir(dir)
local allowed_dirs = config.options.allowed_dirs
if allowed_dirs == nil then
function M.allowed_dir(opts)
if next(config.allowed_dirs) == nil and next(config.ignored_dirs) == nil then
return true
end
return utils.dirs_match(dir, allowed_dirs)
opts = opts or {}
local dir = opts.dir or vim.fn.getcwd()
return utils.dirs_match(dir, config.allowed_dirs) and not utils.dirs_match(dir, config.ignored_dirs)
end
---Is the current working directory ignored for auto-saving and loading?
---@param dir string Directory to be used for the session
---@return boolean
local function ignore_dir(dir)
local ignored_dirs = config.options.ignored_dirs
if ignored_dirs == nil then
return false
end
return utils.dirs_match(dir, ignored_dirs)
end
---Is the current branch ignored for auto-saving and loading?
---@param branch? string Branch to be used for the session
---@return boolean
local function ignore_branch(branch)
local ignored_branches = config.options.ignored_branches
if not branch or ignored_branches == nil then
return false
end
return utils.table_match(branch, ignored_branches) ~= nil
end
---Get the session that was saved last
---@return string
local function get_last()
local sessions = vim.fn.glob(config.options.save_dir .. "*.vim", true, true)
---Get an ordered list of sessions, sorted by modified time
---@return string[]
function M.list()
local sessions = vim.fn.glob(config.save_dir .. "*.vim", true, true)
table.sort(sessions, function(a, b)
return uv.fs_stat(a).mtime.sec > uv.fs_stat(b).mtime.sec
end)
return sessions[1]
return sessions
end
---Get the current Git branch name, untouched
---@param dir? string Directory to be used for the session
---@return string|nil
local function get_branchname(dir)
dir = dir or session_dir()
vim.fn.system('git -C "' .. dir .. '" rev-parse 2>/dev/null')
local git_enabled = (vim.v.shell_error == 0)
if git_enabled then
local git_branch = vim.fn.systemlist('git -C "' .. dir .. '" rev-parse --abbrev-ref HEAD 2>/dev/null')
return git_branch[1]
end
return nil
end
---Get the current Git branch
---@param dir? string Directory to be used for the session
---@return string|nil
function M.get_branch(dir)
dir = dir or session_dir()
if config.options.use_git_branch then
if uv.fs_stat(".git") then
local git_branch = vim.fn.systemlist("git branch --show-current")[1]
if vim.v.shell_error == 0 then
local branch = config.options.branch_separator .. git_branch:gsub("/", "%%")
local branch_session = config.options.save_dir .. dir:gsub(utils.get_dir_pattern(), "%%") .. branch .. ".vim"
-- Try to load the session for the current branch
if vim.fn.filereadable(branch_session) ~= 0 then
return branch
else
log:debug("Trying to load a session for branch: %s", config.options.default_branch)
log:error("Could not load a session for branch: %s", git_branch[1])
vim.g.persisted_branch_session = branch_session
return config.options.branch_separator .. config.options.default_branch
end
end
end
end
end
---Get the current session for the current working directory and git branch
---@param dir string Directory to be used for the session
---Get the last session that was saved
---@return string
local function get_current(dir)
local name = dir:gsub(utils.get_dir_pattern(), "%%")
local branch = M.get_branch(dir)
return config.options.save_dir .. name .. (branch or "") .. ".vim"
end
---Determine if a session for the current wording directory, exists
---@param dir? string Directory to be used for the session
---@return boolean
function M.session_exists(dir)
dir = dir or session_dir()
return vim.fn.filereadable(get_current(dir)) ~= 0
function M.last()
return M.list()[1]
end
---Setup the plugin
---@param opts? table
---@return nil
function M.setup(opts)
config.setup(opts)
-- Account for old config options
if opts and opts.autosave then
opts.autostart = opts.autosave
end
if opts and opts.should_autosave then
opts.should_save = opts.should_autosave
end
if opts and opts.allowed_dirs == nil then
opts.allowed_dirs = {}
end
if opts and opts.ignored_dirs == nil then
opts.ignored_dirs = {}
end
log.set_root(log.new({
handlers = {
{
type = "echo",
level = vim.log.levels.WARN,
},
{
type = "file",
filename = "persisted.log",
level = vim.log.levels[config.options.log_level],
},
},
}))
config = vim.tbl_deep_extend("force", require("persisted.config"), opts or {})
M.config = config
local dir = session_dir()
local branch = get_branchname()
vim.fn.mkdir(config.save_dir, "p")
if
config.options.autosave
and (allow_dir(dir) and not ignore_dir(dir) and vim.g.persisting == nil)
and not ignore_branch(branch)
and args_check()
then
log:trace("Starting session")
if config.autostart and M.allowed_dir() and vim.g.persisting == nil then
M.start()
end
end
---Load a session
---@param opt? table
---@param dir? string Directory to be used for the session
---@return nil
function M.load(opt, dir)
opt = opt or {}
dir = dir or session_dir()
local branch
local session
if opt.session then
session = opt.session
local session_data = utils.make_session_data(session)
branch = session_data and session_data.branch or ""
log:trace("Session branch %s", branch)
log:trace("Session data %s", session_data)
if not branch then
vim.notify(string.format("[Persisted.nvim]: Invalid session file %s", session), vim.log.levels.WARN)
end
else
branch = get_branchname()
session = opt.last and get_last() or get_current(dir)
log:trace("Session branch: %s", branch)
end
if session then
if vim.fn.filereadable(session) ~= 0 then
vim.g.persisting_session = not config.options.follow_cwd and session or nil
log:trace("Session load: %s", session)
utils.load_session(session, config.options.silent)
elseif type(config.options.on_autoload_no_session) == "function" then
log:trace("No session to load")
config.options.on_autoload_no_session()
end
end
dir = session_dir()
if config.options.autosave and (allow_dir(dir) and not ignore_dir(dir)) and not ignore_branch(branch) then
M.start()
end
end
---Automatically load the session for the current dir
---@return nil
function M.autoload()
local dir = session_dir()
local branch = get_branchname()
if config.options.autoload and args_check() then
if allow_dir(dir) and not ignore_dir(dir) and not ignore_branch(branch) then
log:trace("Autoloading from %s", dir)
M.load({}, dir)
end
end
end
---Start recording a session
---@return nil
function M.start()
vim.g.persisting = true
vim.api.nvim_exec_autocmds("User", { pattern = "PersistedStateChange", data = { action = "start" } })
end
---Stop recording a session
---@return nil
function M.stop()
vim.g.persisting = false
vim.g.persisting_session = nil
vim.api.nvim_exec_autocmds("User", { pattern = "PersistedStateChange", data = { action = "stop" } })
end
---Write the session to disk
---@param session string
---@return nil
local function write(session)
vim.api.nvim_exec_autocmds("User", { pattern = "PersistedSavePre" })
vim.cmd("mks! " .. e(session))
vim.g.persisting = true
log:trace("Session saved")
vim.api.nvim_exec_autocmds("User", { pattern = "PersistedSavePost" })
end
---Save the session
---@param opt? table
---@param dir? string Directory to be used for the session
---@return nil
function M.save(opt, dir)
opt = opt or {}
dir = dir or session_dir()
if not opt.session then
-- Do not save the session if the user has manually stopped it...unless it's forced
if (vim.g.persisting == false or vim.g.persisting == nil) and not opt.force then
return
end
-- Do not save the session if autosave is turned off...unless it's forced
if not config.options.autosave and not opt.force then
return
end
-- Do not save the session if the callback returns false...unless it's forced
if
not opt.force
and type(config.options.should_autosave) == "function"
and not config.options.should_autosave()
then
return
end
end
local session = opt.session or (vim.g.persisted_branch_session or vim.g.persisting_session or get_current(dir))
write(session)
end
---Delete the current session
---@param dir? string Directory to be used for the session
---@return nil
function M.delete(dir)
dir = dir or session_dir()
local session = get_current(dir)
if session and uv.fs_stat(session) ~= 0 then
local session_data = utils.make_session_data(session)
vim.api.nvim_exec_autocmds("User", { pattern = "PersistedDeletePre", data = session_data })
vim.schedule(function()
log:trace("Deleting session %s", session)
M.stop()
vim.fn.system("rm " .. e(session))
end)
vim.api.nvim_exec_autocmds("User", { pattern = "PersistedDeletePost", data = session_data })
end
end
---Determines whether to load, start or stop a session
---@param dir? string The directory whose associated session saving should be toggled. If not set, the current working directory is used.
---@return nil
function M.toggle(dir)
vim.api.nvim_exec_autocmds("User", { pattern = "PersistedToggled" })
dir = dir or session_dir()
if vim.g.persisting == nil then
log:trace("Toggling load")
return M.load({}, dir)
end
if vim.g.persisting then
log:trace("Toggling stop")
return M.stop()
end
log:trace("Toggling start")
return M.start()
end
---List all of the sessions
---@return table
function M.list()
local save_dir = config.options.save_dir
local session_files = vim.fn.glob(save_dir .. "*.vim", true, true)
local branch_separator = config.options.branch_separator
local dir_separator = utils.get_dir_pattern()
local sessions = {}
for _, session in pairs(session_files) do
local session_name = escape_pattern(session, save_dir, "")
:gsub("%%", dir_separator)
:gsub(vim.fn.expand("~"), dir_separator)
:gsub("//", "")
:sub(1, -5)
if vim.fn.has("win32") == 1 then
-- format drive letter (no trailing separator)
session_name = escape_pattern(session_name, dir_separator, ":", 1)
-- format remaining filepath separator(s)
session_name = escape_pattern(session_name, dir_separator, "\\")
end
local branch, dir_path
if string.find(session_name, branch_separator, 1, true) then
local splits = vim.split(session_name, branch_separator, { plain = true })
branch = table.remove(splits, #splits)
dir_path = vim.fn.join(splits, branch_separator)
else
dir_path = session_name
end
table.insert(sessions, {
["name"] = session_name,
["file_path"] = session,
["branch"] = branch,
["dir_path"] = dir_path,
})
end
return sessions
end
return M

280
lua/persisted/log.lua
View File

@ -1,280 +0,0 @@
---@type boolean
local is_windows = vim.loop.os_uname().version:match("Windows")
---@type string
local sep = is_windows and "\\" or "/"
---@return string
local join = function(...)
local joined = table.concat({ ... }, sep)
if is_windows then
joined = joined:gsub("\\\\+", "\\")
else
joined = joined:gsub("//+", "/")
end
return joined
end
---@class LogHandler
---@field type string
---@field level integer
---@field formatter? fun(level: integer, msg: string, ...: any)
---@field handle? fun(level: integer, text: string)
local LogHandler = {}
local levels_reverse = {}
for k, v in pairs(vim.log.levels) do
levels_reverse[v] = k
end
function LogHandler.new(opts)
vim.validate({
type = { opts.type, "s" },
handle = { opts.handle, "f" },
formatter = { opts.formatter, "f" },
level = { opts.level, "n", true },
})
return setmetatable({
type = opts.type,
handle = opts.handle,
formatter = opts.formatter,
level = opts.level or vim.log.levels.INFO,
}, { __index = LogHandler })
end
function LogHandler:log(level, msg, ...)
if self.level <= level then
local text = self.formatter(level, msg, ...)
self.handle(level, text)
end
end
local function default_formatter(level, msg, ...)
local args = vim.F.pack_len(...)
for i = 1, args.n do
local v = args[i]
if type(v) == "table" then
args[i] = vim.inspect(v)
elseif v == nil then
args[i] = "nil"
end
end
local ok, text = pcall(string.format, msg, vim.F.unpack_len(args))
if ok then
local str_level = levels_reverse[level]
return string.format("[%s] %s\n%s", str_level, os.date("%Y-%m-%d %H:%M:%S"), text)
else
return string.format("[ERROR] error formatting log line: '%s' args %s", msg, vim.inspect(args))
end
end
---@param opts table
---@return LogHandler
local function create_file_handler(opts)
vim.validate({
filename = { opts.filename, "s" },
})
local ok, stdpath = pcall(vim.fn.stdpath, "log")
if not ok then
stdpath = vim.fn.stdpath("cache")
end
local filepath = join(stdpath, opts.filename)
local logfile, openerr = io.open(filepath, "a+")
if not logfile then
local err_msg = string.format("Failed to open the CodeCompanion log file: %s", openerr)
vim.notify(err_msg, vim.log.levels.ERROR)
opts.handle = function() end
else
opts.handle = function(level, text)
logfile:write(text)
logfile:write("\n")
logfile:flush()
end
end
return LogHandler.new(opts)
end
---@param opts table
---@return LogHandler
local function create_notify_handler(opts)
opts.handle = function(level, text)
vim.notify(text, level)
end
return LogHandler.new(opts)
end
---@param opts table
---@return LogHandler
local function create_echo_handler(opts)
opts.handle = function(level, text)
local hl = "Normal"
if level == vim.log.levels.ERROR then
hl = "DiagnosticError"
elseif level == vim.log.levels.WARN then
hl = "DiagnosticWarn"
end
vim.api.nvim_echo({ { text, hl } }, true, {})
end
return LogHandler.new(opts)
end
---@return LogHandler
local function create_null_handler()
return LogHandler.new({
formatter = function() end,
handle = function() end,
})
end
---@param opts table
---@return LogHandler
local function create_handler(opts)
vim.validate({
type = { opts.type, "s" },
})
if not opts.formatter then
opts.formatter = default_formatter
end
if opts.type == "file" then
return create_file_handler(opts)
elseif opts.type == "notify" then
return create_notify_handler(opts)
elseif opts.type == "echo" then
return create_echo_handler(opts)
else
vim.notify(string.format("Unknown log handler %s", opts.type), vim.log.levels.ERROR)
return create_null_handler()
end
end
---@class Logger
---@field handlers LogHandler[]
local Logger = {}
---@class LoggerArgs
---@field handlers LogHandler[]
---@field level nil|integer
---@param opts LoggerArgs
function Logger.new(opts)
vim.validate({
handlers = { opts.handlers, "t" },
level = { opts.level, "n", true },
})
local handlers = {}
for _, defn in ipairs(opts.handlers) do
table.insert(handlers, create_handler(defn))
end
local log = setmetatable({
handlers = handlers,
}, { __index = Logger })
if opts.level then
log:set_level(opts.level)
end
return log
end
---@param level integer
function Logger:set_level(level)
for _, handler in ipairs(self.handlers) do
handler.level = level
end
end
---@return LogHandler[]
function Logger:get_handlers()
return self.handlers
end
---@param level integer
---@param msg string
---@param ... any[]
function Logger:log(level, msg, ...)
for _, handler in ipairs(self.handlers) do
handler:log(level, msg, ...)
end
end
---@param msg string
---@param ... any
function Logger:trace(msg, ...)
self:log(vim.log.levels.TRACE, msg, ...)
end
---@param msg string
---@param ... any
function Logger:debug(msg, ...)
self:log(vim.log.levels.DEBUG, msg, ...)
end
---@param msg string
---@param ... any
function Logger:info(msg, ...)
self:log(vim.log.levels.INFO, msg, ...)
end
---@param msg string
---@param ... any
function Logger:warn(msg, ...)
self:log(vim.log.levels.WARN, msg, ...)
end
---@param msg string
---@param ... any
function Logger:error(msg, ...)
self:log(vim.log.levels.ERROR, msg, ...)
end
---@generic T : any
---@param cb T
---@param message nil|string
---@return T
function Logger:wrap_cb(cb, message)
return function(err, ...)
if err then
self:error(message or "Error: %s", err)
end
return cb(err, ...)
end
end
local root = Logger.new({
handlers = {
{
type = "echo",
level = vim.log.levels.WARN,
},
},
})
---@class Logger
local M = {}
M.new = Logger.new
M.get_logfile = function()
local ok, stdpath = pcall(vim.fn.stdpath, "log")
if not ok then
stdpath = vim.fn.stdpath("cache")
end
return join(stdpath, "persisted.log")
end
---@param logger Logger
M.set_root = function(logger)
root = logger
end
---@return Logger
M.get_root = function()
return root
end
setmetatable(M, {
__index = function(_, key)
return root[key]
end,
})
return M

128
lua/persisted/utils.lua
View File

@ -1,23 +1,19 @@
local M = {}
local e = vim.fn.fnameescape
local fp_sep = vim.loop.os_uname().sysname:lower():match("windows") and "\\" or "/" -- \ for windows, mac and linux both use \
---Print an error message
--@param msg string
--@param error string
--@return string
local function echoerr(msg, error)
vim.api.nvim_echo({
{ "[Persisted.nvim]: ", "ErrorMsg" },
{ msg, "WarningMsg" },
{ error, "Normal" },
}, true, {})
---Get the directory pattern based on OS
---@return string
function M.dir_pattern()
local pattern = "/"
if vim.fn.has("win32") == 1 then
pattern = "[\\:]"
end
return pattern
end
--- Escape special pattern matching characters in a string
---@param input string
---@return string
local function escape_pattern(input)
function M.escape_dir_pattern(input)
local magic_chars = { "%", "(", ")", ".", "+", "-", "*", "?", "[", "^", "$" }
for _, char in ipairs(magic_chars) do
@ -27,117 +23,47 @@ local function escape_pattern(input)
return input
end
---Form a table of session data
---@param session string
---@return table|nil
function M.make_session_data(session)
local config = require("persisted.config").options
local home = os.getenv("HOME") or os.getenv("USERPROFILE") or ""
-- Split the session string into path and branch parts
local separator_index = session:find(config.branch_separator)
local branch = ""
if separator_index then
branch = session:sub(separator_index + 2):gsub("%.vim$", ""):gsub("%%", "/")
end
-- Removing the home directory from the path and cleaning leading `/`
local name = session:gsub(config.save_dir, ""):gsub("%%", "/"):gsub(home, "")
-- Remove the .vim extension
name = name:sub(1, #name - 4)
if name:sub(1, 1) == "/" then
name = name:sub(2)
end
local dir_path = name:gsub(branch, ""):gsub(config.branch_separator, ""):gsub(home, "")
return {
name = name,
dir_path = dir_path,
file_path = session,
branch = branch,
}
end
--- Get the last element in a table
---@param table table
---@return string
function M.get_last_item(table)
local last
for _, _ in pairs(table) do
last = #table - 0
end
return table[last]
end
---Check if a target directory exists in a given table
---@param dir string
---@param dirs_table table
---@return boolean
function M.dirs_match(dir, dirs_table)
dir = vim.fn.expand(dir)
return M.table_match(dir, dirs_table, function(pattern)
return escape_pattern(vim.fn.expand(pattern))
local match = M.in_table(dir, dirs_table, function(pattern)
return M.escape_dir_pattern(vim.fn.expand(pattern))
end)
return match
end
---Check if a string matches and entry in a given table
---@param needle string
---@param heystack table
---@param val string
---@param tbl table
---@param callback function
---@return boolean
function M.table_match(needle, heystack, escape_fct)
if needle == nil then
function M.in_table(val, tbl, callback)
if val == nil then
return false
end
return heystack
return tbl
and next(vim.tbl_filter(function(pattern)
if pattern.exact then
-- The pattern is actually a table
pattern = pattern[1]
-- Stripping off the trailing backslash that a user might put here,
-- but only if we aren't looking at the root directory
if pattern:sub(-1) == fp_sep and pattern:len() > 1 then
if pattern:sub(-1) == M.dir_pattern() and pattern:len() > 1 then
pattern = pattern:sub(1, -2)
end
return needle == pattern
return val == pattern
else
if escape_fct then
pattern = escape_fct(pattern)
if callback and type(callback) == "function" then
pattern = callback(pattern)
end
return needle:match(pattern)
return val:match(pattern)
end
end, heystack))
end
---Get the directory pattern based on OS
---@return string
function M.get_dir_pattern()
local pattern = "/"
if vim.fn.has("win32") == 1 then
pattern = "[\\:]"
end
return pattern
end
---Load the given session
---@param session string
---@param silent boolean Load the session silently?
---@return nil|string
function M.load_session(session, silent)
local session_data = M.make_session_data(session)
vim.api.nvim_exec_autocmds("User", { pattern = "PersistedLoadPre", data = session_data })
local ok, result = pcall(vim.cmd, (silent and "silent " or "") .. "source " .. e(session))
if not ok then
return echoerr("Error loading the session! ", result)
end
vim.g.persisted_exists = true
vim.g.persisted_loaded_session = session
vim.api.nvim_exec_autocmds("User", { pattern = "PersistedLoadPost", data = session_data })
end, tbl))
end
return M

72
lua/telescope/_extensions/persisted.lua
View File

@ -6,23 +6,79 @@ local action_state = require("telescope.actions.state")
local _actions = require("telescope._extensions.persisted.actions")
local _finders = require("telescope._extensions.persisted.finders")
local persisted = require("persisted")
local utils = require("persisted.utils")
local config = persisted.config
local telescope_opts = {}
---Escapes special characters before performing string substitution
---@param str string
---@param pattern string
---@param replace string
---@param n? integer
---@return string
---@return integer
local function escape_pattern(str, pattern, replace, n)
pattern = string.gsub(pattern, "[%(%)%.%+%-%*%?%[%]%^%$%%]", "%%%1") -- escape pattern
replace = string.gsub(replace, "[%%]", "%%%%") -- escape replacement
return string.gsub(str, pattern, replace, n)
end
---List all of the available sessions
local function list_sessions()
local sep = utils.dir_pattern()
local sessions = {}
for _, session in pairs(persisted.list()) do
local session_name = escape_pattern(session, config.save_dir, "")
:gsub("%%", sep)
:gsub(vim.fn.expand("~"), sep)
:gsub("//", "")
:sub(1, -5)
if vim.fn.has("win32") == 1 then
session_name = escape_pattern(session_name, sep, ":", 1)
session_name = escape_pattern(session_name, sep, "\\")
end
local branch, dir_path
if string.find(session_name, "@@", 1, true) then
local splits = vim.split(session_name, "@@", { plain = true })
branch = table.remove(splits, #splits)
dir_path = vim.fn.join(splits, "@@")
else
dir_path = session_name
end
table.insert(sessions, {
["name"] = session_name,
["file_path"] = session,
["branch"] = branch,
["dir_path"] = dir_path,
})
end
return sessions
end
---Search through the Persisted sessions
---@param opts table
local function search_sessions(opts)
local config = require("persisted.config").options
opts = vim.tbl_extend("force", telescope_opts, opts or {})
pickers
.new(opts, {
prompt_title = "Sessions",
sorter = conf.generic_sorter(opts),
finder = _finders.session_finder(require("persisted").list()),
finder = _finders.session_finder(list_sessions()),
attach_mappings = function(prompt_bufnr, map)
local refresh_sessions = function()
local picker = action_state.get_current_picker(prompt_bufnr)
picker:refresh(_finders.session_finder(require("persisted").list()), {
-- INFO: Account for users who are still using the old API
reset_prompt = config.telescope.reset_prompt or config.telescope.reset_prompt_after_deletion,
picker:refresh(_finders.session_finder(list_sessions()), {
reset_prompt = true,
})
end
@ -53,9 +109,9 @@ end
return require("telescope").register_extension({
setup = function(topts)
vim.api.nvim_set_hl(0, "TelescopePersistedIsCurrent", { link = "TelescopeResultsOperator" })
vim.api.nvim_set_hl(0, "TelescopePersistedDir", { link = "Directory" })
vim.api.nvim_set_hl(0, "TelescopePersistedBranch", { link = "TelescopeResultsIdentifier" })
vim.api.nvim_set_hl(0, "PersistedTelescopeSelected", { link = "TelescopeResultsOperator", default = true })
vim.api.nvim_set_hl(0, "PersistedTelescopeDir", { link = "Directory", default = true })
vim.api.nvim_set_hl(0, "PersistedTelescopeBranch", { link = "TelescopeResultsIdentifier", default = true })
telescope_opts = topts
end,
exports = {

38
lua/telescope/_extensions/persisted/actions.lua
View File

@ -2,43 +2,43 @@ local actions_state = require("telescope.actions.state")
local transform_mod = require("telescope.actions.mt").transform_mod
local persisted = require("persisted")
local config = persisted.config
local M = {}
---Fire an event
---@param event string
local function fire(event)
vim.api.nvim_exec_autocmds("User", { pattern = "Persisted" .. event })
end
---Get the selected session from Telescope
---@return table
local get_selected_session = function()
local function get_selected_session()
return actions_state.get_selected_entry()
end
---Load the selected session
---@param session table
---@param config table
---@return nil
M.load_session = function(session, config)
vim.api.nvim_exec_autocmds("User", { pattern = "PersistedTelescopeLoadPre", data = session })
function M.load_session(session)
fire("TelescopeLoadPre")
vim.schedule(function()
persisted.load({ session = session.file_path })
end)
vim.api.nvim_exec_autocmds("User", { pattern = "PersistedTelescopeLoadPost", data = session })
fire("TelescopeLoadPost")
end
---Delete the selected session from disk
--@return nil
M.delete_session = function()
function M.delete_session()
local session = get_selected_session()
local path = session.file_path
if vim.fn.confirm("Delete [" .. session.name .. "]?", "&Yes\n&No") == 1 then
vim.fn.delete(vim.fn.expand(path))
vim.fn.delete(vim.fn.expand(session.file_path))
end
end
---Change the branch of an existing session
---@param config table
---@return nil
M.change_branch = function(config)
function M.change_branch()
local session = get_selected_session()
local path = session.file_path
@ -48,8 +48,7 @@ M.change_branch = function(config)
local ext = path:match("^.+(%..+)$")
-- Check for existing branch in the filename
local branch_separator = config.branch_separator or "@@"
local pattern = "(.*)" .. branch_separator .. ".+" .. ext .. "$"
local pattern = "(.*)@@.+" .. ext .. "$"
local base = path:match(pattern) or path:sub(1, #path - #ext)
-- Replace or add the new branch name
@ -57,7 +56,7 @@ M.change_branch = function(config)
if branch == "" then
new_path = base .. ext
else
new_path = base .. branch_separator .. branch .. ext
new_path = base .. "@@" .. branch .. ext
end
os.rename(path, new_path)
@ -65,8 +64,7 @@ M.change_branch = function(config)
end
---Copy an existing session
---@return nil
M.copy_session = function(config)
function M.copy_session()
local session = get_selected_session()
local old_name = session.file_path:gsub(config.save_dir, "")

18
lua/telescope/_extensions/persisted/finders.lua
View File

@ -1,16 +1,18 @@
local config = require("persisted.config")
local config = require("persisted").config
local finders = require("telescope.finders")
local M = {}
local no_icons = {
branch = "",
dir = "",
selected = "",
dir = "",
branch = "",
}
M.session_finder = function(sessions)
local icons = vim.tbl_extend("force", no_icons, config.options.telescope.icons or {})
---Create a finder for persisted sessions
---@param sessions table
function M.session_finder(sessions)
local icons = vim.tbl_extend("force", no_icons, config.telescope.icons or {})
local custom_displayer = function(session)
local final_str = ""
@ -25,15 +27,15 @@ M.session_finder = function(sessions)
end
-- is current session
append(session.file_path == vim.v.this_session and (icons.selected .. " ") or " ", "TelescopePersistedIsCurrent")
append(session.file_path == vim.v.this_session and (icons.selected .. " ") or " ", "PersistedTelescopeSelected")
-- session path
append(icons.dir, "TelescopePersistedDir")
append(icons.dir, "PersistedTelescopeDir")
append(session.dir_path)
-- branch
if session.branch then
append(" " .. icons.branch .. session.branch, "TelescopePersistedBranch")
append(" " .. icons.branch .. session.branch, "PersistedTelescopeBranch")
end
return final_str, hls

18
plugin/persisted.lua
View File

@ -2,33 +2,19 @@ if vim.g.loaded_persisted then
return
end
local persisted = require("persisted")
-- Create the user commands
vim.cmd([[command! SessionStart :lua require("persisted").start()]])
vim.cmd([[command! SessionStop :lua require("persisted").stop()]])
vim.cmd([[command! SessionSave :lua require("persisted").save({ force = true })]])
vim.cmd([[command! SessionLoad :lua require("persisted").load()]])
vim.cmd([[command! SessionLoadLast :lua require("persisted").load({ last = true })]])
vim.cmd([[command! -nargs=1 SessionLoadFromFile :lua require("persisted").load({ session = <f-args> })]])
vim.cmd([[command! SessionDelete :lua require("persisted").delete()]])
vim.cmd([[command! SessionToggle :lua require("persisted").toggle()]])
-- Create the autocmds
local group = vim.api.nvim_create_augroup("Persisted", {})
local persisted = require("persisted")
vim.api.nvim_create_autocmd({ "VimEnter" }, {
group = group,
vim.api.nvim_create_autocmd("VimEnter", {
nested = true,
callback = persisted.autoload,
})
vim.api.nvim_create_autocmd({ "VimLeavePre" }, {
group = group,
nested = true,
callback = function()
persisted.save()
vim.cmd('sleep 10m')
end
})
vim.g.loaded_persisted = true

21
tests/default_settings_spec.lua
View File

@ -8,7 +8,7 @@ describe("With default settings:", function()
-- vim.fn.system("rm -rf " .. e(session_dir))
end)
it("it saves a session", function()
it("saves a session", function()
-- Check no file exists
assert.equals(vim.fn.system("ls tests/default_data | wc -l"):gsub("%s+", ""), "0")
@ -24,7 +24,7 @@ describe("With default settings:", function()
assert.equals("1", vim.fn.system("ls tests/default_data | wc -l"):gsub("%s+", ""))
end)
it("it loads a session", function()
it("loads a session", function()
-- Load a session
require("persisted").load()
@ -35,19 +35,19 @@ describe("With default settings:", function()
assert.equals(vim.g.persisting, true)
end)
it("it stops a session", function()
it("stops a session", function()
require("persisted").stop()
assert.equals(vim.g.persisting, false)
end)
it("it starts a session", function()
it("starts a session", function()
require("persisted").start()
assert.equals(vim.g.persisting, true)
end)
it("it lists sessions", function()
it("lists sessions", function()
local sessions = require("persisted").list()
local path = require("plenary.path"):new(sessions[1].file_path)
@ -59,19 +59,10 @@ local async = require("plenary.async.tests")
local util = require("plenary.async.util")
async.describe("With default settings:", function()
async.it("it deletes a session", function()
async.it("deletes a session", function()
require("persisted").delete()
util.scheduler()
assert.equals("0", vim.fn.system("ls tests/default_data | wc -l"):gsub("%s+", ""))
end)
end)
describe("Utilities", function()
it("can make derive the session name", function()
local session = "%home%username%projects%front@@user%fix-analytics-export-null-values.vim"
local data = require("persisted.utils").make_session_data(session)
assert.equals("home/username/projects/front@@user/fix-analytics-export-null-values", data.name)
end)
end)

25
tests/follow_cwd/follow_cwd_spec.lua
View File

@ -1,15 +1,13 @@
pcall(vim.fn.system, "rm -rf tests/dummy_data")
local session_dir = vim.fn.getcwd() .. "/tests/dummy_data/"
-- follow_cwd = true
pcall(vim.fn.system, "rm -rf tests/dummy_data")
require("persisted").setup({
save_dir = session_dir,
follow_cwd = true,
})
describe("Follow cwd change", function()
it("creates two sessions with change in cwd", function()
describe("Follow cwd", function()
it("creates two sessions", function()
vim.cmd(":e tests/stubs/test_autoload.txt")
vim.cmd(":w")
@ -19,15 +17,15 @@ describe("Follow cwd change", function()
require("persisted").save()
vim.cmd(":bdelete")
end)
it("ensures both sessions were created", function()
require("persisted").load()
local pattern = "/"
local branch1 = require("persisted").get_branch()
local name1 = vim.fn.getcwd():gsub(pattern, "%%") .. (branch1 or "") .. ".vim"
local name1 = vim.fn.getcwd():gsub(pattern, "%%") .. ".vim"
vim.cmd(":cd ../..")
local branch2 = require("persisted").get_branch()
local name2 = vim.fn.getcwd():gsub(pattern, "%%") .. (branch2 or "") .. ".vim"
local name2 = vim.fn.getcwd():gsub(pattern, "%%") .. ".vim"
local sessions = vim.fn.readdir(session_dir)
assert.equals(sessions[1], name1)
@ -35,14 +33,13 @@ describe("Follow cwd change", function()
end)
end)
-- follow_cwd = false
pcall(vim.fn.system, "rm -rf tests/dummy_data")
require("persisted").setup({
save_dir = session_dir,
follow_cwd = false,
})
describe("Don't follow cwd change", function()
describe("Follow a cwd change", function()
it("creates two sessions with change in cwd", function()
vim.cmd(":e tests/stubs/test_autoload.txt")
vim.cmd(":w")
@ -56,11 +53,11 @@ describe("Don't follow cwd change", function()
it("ensures only one session was created", function()
local pattern = "/"
vim.cmd(":cd ../..")
local branch = require("persisted").get_branch()
local name = vim.fn.getcwd():gsub(pattern, "%%") .. (branch or "") .. ".vim"
local name = vim.fn.getcwd():gsub(pattern, "%%") .. ".vim"
local sessions = vim.fn.readdir(session_dir)
assert.equals(#sessions, 1)
assert.equals(name, sessions[1])
assert.equals(sessions[1], name)
end)
end)

17
tests/git_branching/git_branching_spec.lua
View File

@ -21,9 +21,24 @@ describe("Git Branching", function()
end)
it("ensures the session has the branch name in", function()
if vim.fn.isdirectory(session_dir .. "/.git") == 0 then
vim.fn.system("mkdir -p " .. session_dir)
vim.fn.system("cd " .. session_dir .. " && git init")
end
local branch_name = require("persisted").branch()
-- Check if branch_name is valid
if not branch_name then
print("Failed to get branch name.")
branch_name = ""
else
branch_name = "@@" .. branch_name
end
-- Workout what the name should be
local pattern = "/"
local name = vim.fn.getcwd():gsub(pattern, "%%") .. require("persisted").get_branch() .. ".vim"
local name = vim.fn.getcwd():gsub(pattern, "%%") .. branch_name .. ".vim"
local session = vim.fn.glob(session_dir .. "*.vim", true, true)[1]
session:gsub(session_dir .. "/", "")