From d951015e5b7594b3a3c4c088571c16c440de20af Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 21 Feb 2023 21:51:35 +0000 Subject: [PATCH] chore(build): auto-generate vimdoc --- doc/persisted.nvim.txt | 409 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 409 insertions(+) diff --git a/doc/persisted.nvim.txt b/doc/persisted.nvim.txt index e69de29..1dfdc84 100644 --- a/doc/persisted.nvim.txt +++ b/doc/persisted.nvim.txt @@ -0,0 +1,409 @@ +*persisted.nvim.txt* For Neovim >= 0.7.0 Last change: 2023 February 21 + +============================================================================== +Table of Contents *persisted.nvim-table-of-contents* + + - Features |persisted.nvim-nil-features| + - Requirements |persisted.nvim-nil-requirements| + - Installation |persisted.nvim-nil-installation| + - Usage |persisted.nvim-nil-usage| + - Configuration |persisted.nvim-nil-configuration| + - License |persisted.nvim-nil-license| +Persisted.nvim + + +Persisted.nvim is a simple lua plugin for automated session management within Neovim +Forked from Persistence.nvim as active development had stopped +FEATURES *persisted.nvim-nil-features* + + +- Automatically saves the active session under `.local/share/nvim/sessions` on exiting Neovim +- Supports sessions across multiple git branches +- Supports auto saving and loading of sessions with allowed/ignored directories +- Simple API to save/stop/restore/delete/list the current session(s) +- Telescope extension to work with saved sessions + + +REQUIREMENTS *persisted.nvim-nil-requirements* + + +- Neovim >= 0.7.0 + + +INSTALLATION *persisted.nvim-nil-installation* + +Install the plugin with your preferred package manager: + +**Lazy.nvim** + +>lua + -- Lua + use({ + "olimorris/persisted.nvim" + -- lazy = true, -- For lazy loading + config = true + }) +< + +**Packer** + +>lua + -- Lua + use({ + "olimorris/persisted.nvim", + --module = "persisted", -- For lazy loading + config = function() + require("persisted").setup() + end, + }) +< + +**Vim Plug** + +>vim + " Vim Script + Plug 'olimorris/persisted.nvim' + + lua << EOF + require("persisted").setup { + -- your configuration comes here + -- or leave it empty to use the default settings + -- refer to the configuration section below + } + EOF +< + + +TELESCOPE EXTENSION ~ + +Ensure that the telescope extension is loaded with: + +>lua + require("telescope").load_extension("persisted") +< + + +LAZY LOADING ~ + +The plugin is designed to work with startup screens like vim-startify + or dashboard + out of the box. It will never load +a session automatically by default. + +However, to lazy load the plugin add the `module = "persisted"` line to packer +or `lazy = true` for Lazy.nvim. + + +USAGE *persisted.nvim-nil-usage* + +**Default commands** + +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` +- `: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` +- `:SessionLoadLast` - Load the most recent session +- `:SessionLoadFromPath` - Load a session from a given path +- `:SessionDelete` - Delete the current session + + + **Note:** The author only binds `:SessionToggle` to a keymap for simplicity. +**Telescope** + +The Telescope extension may be opened via `:Telescope persisted`. + +Once opened, the available keymaps are: `` - Source the session file +`` - Delete the session file + +**Helpers** + +The plugin sets a global variable, `vim.g.persisting`, which is set to `true` +when a session is started. The author uses this to display an icon in their +statusline +. + + +CONFIGURATION *persisted.nvim-nil-configuration* + + +DEFAULTS ~ + +The plugin comes with the following defaults: + +>lua + require("persisted").setup({ + save_dir = vim.fn.expand(vim.fn.stdpath("data") .. "/sessions/"), -- directory where session files are saved + command = "VimLeavePre", -- the autocommand for which the session is saved + silent = false, -- silent nvim message when sourcing session file + use_git_branch = false, -- create session files based on the branch of the git enabled repository + 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 + before_save = nil, -- function to run before the session is saved to disk + after_save = nil, -- function to run after the session is saved to disk + after_source = nil, -- function to run after the session is sourced + telescope = { -- options for the telescope extension + before_source = nil, -- function to run before the session is sourced via telescope + after_source = nil, -- function to run after the session is sourced via telescope + reset_prompt_after_deletion = true, -- whether to reset prompt after session deleted + }, + }) +< + + +SESSION OPTIONS ~ + +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,winpos,winsize"` + +SESSION SAVE LOCATION ~ + +The location of the session files may be changed by altering the `save_dir` +configuration option. For example: + +>lua + require("persisted").setup({ + save_dir = vim.fn.expand(vim.fn.stdpath("data") .. "/sessions/"), -- Resolves to ~/.local/share/nvim/sessions/ + }) +< + + + **Note:** The plugin may be unable to find existing sessions if the `save_dir` + value is changed + +AUTOCMD TO SAVE SESSION ~ + +By default, a session is saved to disk when the `VimLeavePre` autocommand is +triggered. This can be modified by: + +>lua + require("persisted").setup({ + command = "VimLeavePre", + }) +< + + + **Note:** See `:h autocmds` for more information on possible autocmds Git + branching +One of the plugin’s core features is the ability to have multiple sessions +files for a given project, by using git branches. To enable git branching: + +>lua + require("persisted").setup({ + use_git_branch = true, + }) +< + + + **Note:** If git branching is enabled on a non git enabled repo, then `main` + will be used as the default branch + +AUTOSAVING ~ + +By default, the plugin will automatically save a Neovim session to disk when +the `VimLeavePre` autocommand is triggered. Autosaving can be turned off by: + +>lua + require("persisted").setup({ + autosave = false, + }) +< + +Autosaving 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 terminal are open. To control this, a callback function, +`should_autosave`, may be specified. This function should return a boolean +value. + +>lua + require("persisted").setup({ + should_autosave = function() + -- do not autosave if the alpha dashboard is the current filetype + if vim.bo.filetype == "alpha" then + return false + end + return true + end, + }) +< + + +AUTOLOADING ~ + +The plugin can be enabled to automatically load sessions when Neovim is +started. Whilst off by default, this can be turned on by: + +>lua + require("persisted").setup({ + autoload = true, + }) +< + +You can also provide a function to run when `autoload = true` but there is no +session to be loaded: + +>lua + require("persisted").setup({ + autoload = true, + on_autoload_no_session = function() + vim.notify("No existing session to load.") + end + }) +< + +Autoloading can be further controlled for certain directories by specifying +`allowed_dirs` and `ignored_dirs`. + + + **Note:** Autoloading will not occur if a user opens Neovim with arguments. For + example: `nvim some_file.rb` + +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`. + +ALLOWED DIRECTORIES ~ + +You may specify a table of directories for which the plugin will autosave +and/or autoload from. For example: + +>lua + require("persisted").setup({ + allowed_dirs = { + "~/.dotfiles", + "~/Code", + }, + }) +< + +Specifying `~/Code` will autosave 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 + +IGNORED DIRECTORIES ~ + +You may specify a table of directories for which the plugin will **never** +autosave and autoload from. For example: + +>lua + require("persisted").setup({ + ignored_dirs = { + "~/.config", + "~/.local/nvim" + }, + }) +< + +Specifying `~/.config` will prevent any autosaving and autoloading from that +directory as well as all its sub-directories. + + +CALLBACKS ~ + +The plugin allows for _before_ and _after_ callbacks to be executed in relation +to a session being saved. This is achieved via the `before_save` and +`after_save` configuration options: + +>lua + require("persisted").setup({ + before_save = function() + pcall(vim.cmd, "bw minimap") + end, + after_save = function() + print("Session was saved!") + end, + }) +< + + + **Note:** The author uses a _before_ callback to ensure that minimap.vim + is not written into the session. Its + presence prevents the exact buffer and cursor position from being restored when + loading a session +The plugin allows for _before_ and _after_ callbacks to be executed in relation +to a session being sourced: + +>lua + require("persisted").setup({ + before_source = function() + print("Sourcing...") + end, + after_source = function() + -- Reload the LSP servers + vim.lsp.stop_client(vim.lsp.get_active_clients()) + end + }) +< + + +TELESCOPE EXTENSION ~ + +The plugin contains an extension for telescope.nvim + which allows the user to +list all of the saved session files and source them via `:Telescope persisted`. + +**Telescope callbacks** + +The plugin allows for _before_ and _after_ callbacks to be used when sourcing a +session via Telescope. For example: + +>lua + require("persisted").setup({ + telescope = { + before_source = function() + vim.api.nvim_input(":%bd") + end, + after_source = function(session) + print("Loaded session " .. session.name) + end, + }, + }) +< + +The callbacks can accept a _session_ parameter which is a table that has the +following properties: `name` - The filename of the session `file_path` - The +file path to the session `branch` - The git branch of the session + + +LICENSE *persisted.nvim-nil-license* + +MIT + +Generated by panvimdoc + +vim:tw=78:ts=8:noet:ft=help:norl: