christoph/flake-nixinator
1
Fork 0
Code Activity

Update generated neovim config

Browse Source
This commit is contained in:
Christoph Urlacher
2024-09-22 20:41:25 +02:00
parent 1743764e48
commit aa1271c42c
1247 changed files with 26512 additions and 15067 deletions
Download Patch File Download Diff File Expand all files Collapse all files

311
config/neovim/store/lazy-plugins/persisted.nvim/doc/persisted.nvim.txt
View File

@ -8,14 +8,13 @@ Table of Contents *persisted.nvim-table-of-contents*
- Installation |persisted.nvim-installation|
- Usage |persisted.nvim-usage|
- Configuration |persisted.nvim-configuration|
- License |persisted.nvim-license|
- Extending the Plugin |persisted.nvim-extending-the-plugin|
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,13 +22,12 @@ FEATURES *persisted.nvim-features*
REQUIREMENTS *persisted.nvim-requirements*
- Neovim >= 0.8.0
INSTALLATION *persisted.nvim-installation*
Install the plugin with your preferred package manager:
Install and configure the plugin with your preferred package manager:
**Lazy.nvim**
@ -106,11 +104,11 @@ 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
- `:SessionSelect` - Load a session from the list (useful if you don’t wish to use the Telescope extension)
- `:SessionLoad` - Load the session for the current directory and current branch (if `git_use_branch = true`)
- `:SessionLoadLast` - Load the most recent session
- `:SessionLoadFromFile` - Load a session from a given path
@ -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,52 @@ 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
{
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
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 +211,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 +245,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 +259,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 +271,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 +291,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 +334,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 +346,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 +357,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,39 +369,120 @@ 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.
**Custom Autoloading** by neandrake <https://github.com/neandrake>
Autoloading a session if arguments are passed to Neovim:
>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",
"olimorris/persisted.nvim",
lazy = false,
opts = {
autoload = true,
},
}
<
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)
-- Somewhere in your config
local persisted = require("persisted")
vim.api.nvim_create_autocmd("VimEnter", {
nested = true,
callback = function()
if vim.g.started_with_stdin then
return
end
local forceload = false
if vim.fn.argc() == 0 then
forceload = true
elseif vim.fn.argc() == 1 then
local dir = vim.fn.expand(vim.fn.argv(0))
if dir == '.' then
dir = vim.fn.getcwd()
end
if vim.fn.isdirectory(dir) ~= 0 then
forceload = true
end
end
persisted.autoload({ force = forceload })
end,
})
<
**Git Branching from directories that are not the CWD** by mrloop
<https://github.com/mrloop>
[!NOTE] This data is available for the `PersistedLoad`, `PersistedDelete` and
`PersistedTelescope` events
As per #149 <https://github.com/olimorris/persisted.nvim/discussions/149>, if
you invoke Neovim from a sub-directory then the git branch will not be
detected. The code below amends for this:
LICENSE *persisted.nvim-license*
>lua
{
"olimorris/persisted.nvim",
lazy = false,
opts = {
autoload = true,
autosave = true,
use_git_branch = true,
},
config = function(_, opts)
local persisted = require("persisted")
persisted.branch = function()
local branch = vim.fn.systemlist("git branch --show-current")[1]
return vim.v.shell_error == 0 and branch or nil
end
persisted.setup(opts)
end,
}
<
MIT <https://github.com/olimorris/persisted.nvim/blob/main/LICENSE>
**Ignore Branches**
If you’d like to ignore certain branches from being saved as a session:
>lua
{
"olimorris/persisted.nvim",
lazy = false,
opts = {
autostart = true,
use_git_branch = true,
},
config = function(_, opts)
local persisted = require("persisted")
local utils = require("persisted.utils")
local ignored_branches = {
"feature_branch"
}
persisted.setup(opts)
if not utils.in_table(persisted.branch(), ignored_branches) then
persisted.load()
persisted.start()
end
end
}
<
Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>