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

docs: update README.md

main
olimorris 2024-07-02 19:32:25 +01:00
parent a9138468f9
commit 7c30116fc1
2 changed files with 37 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
README.md
View File

@ -80,7 +80,7 @@ EOF
If you wish to use session _autoloading_ alongside a dashboard plugin, it is recommended that you give this plugin a greater loading priority. With **Packer** the `after` config option can be used and in **Lazy.nvim**, the `priority` property. If you wish to use session _autoloading_ alongside a dashboard plugin, it is recommended that you give this plugin a greater loading priority. With **Packer** the `after` config option can be used and in **Lazy.nvim**, the `priority` property.
### Telescope extension **Telescope extension**
Ensure that the telescope extension is loaded with: Ensure that the telescope extension is loaded with:
@ -105,7 +105,7 @@ require('telescope').setup({
## :rocket: Usage ## :rocket: Usage
### Commands **Commands**
The plugin comes with a number of commands: The plugin comes with a number of commands:
@ -118,7 +118,7 @@ The plugin comes with a number of commands:
- `:SessionLoadFromFile` - Load a session from a given path - `:SessionLoadFromFile` - Load a session from a given path
- `:SessionDelete` - Delete the current session - `:SessionDelete` - Delete the current session
### Telescope extension **Telescope extension**
<!-- panvimdoc-ignore-start --> <!-- panvimdoc-ignore-start -->
@ -135,7 +135,7 @@ The Telescope extension may be opened via `:Telescope persisted`. The available
- `<C-c>` - Copy the session file - `<C-c>` - Copy the session file
- `<C-d>` - Delete the session file - `<C-d>` - Delete the session file
### Global variables **Global variables**
The plugin sets a number of global variables throughout its lifecycle: The plugin sets a number of global variables throughout its lifecycle:
@ -145,12 +145,13 @@ The plugin sets a number of global variables throughout its lifecycle:
## :wrench: Configuration ## :wrench: Configuration
### Defaults **Defaults**
The plugin comes with the following defaults: The plugin comes with the following defaults:
```lua ```lua
require("persisted").setup({ 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 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 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 use_git_branch = false, -- create session files based on the branch of a git enabled repository
@ -179,14 +180,14 @@ require("persisted").setup({
}) })
``` ```
### What is saved in the session? **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. 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] > [!NOTE]
> The author uses: `vim.o.sessionoptions = "buffers,curdir,folds,tabpages,winpos,winsize"` > The author uses: `vim.o.sessionoptions = "buffers,curdir,folds,tabpages,winpos,winsize"`
### Session save location **Session save location**
The location of the session files may be changed by altering the `save_dir` configuration option. For example: The location of the session files may be changed by altering the `save_dir` configuration option. For example:
@ -199,7 +200,7 @@ require("persisted").setup({
> [!NOTE] > [!NOTE]
> The plugin may be unable to find existing sessions if the `save_dir` value is changed > The plugin may be unable to find existing sessions if the `save_dir` value is changed
### Git branching **Git branching**
One of the plugin's core features is the ability to have multiple session files for a given project, by using git branches. To enable git branching: One of the plugin's core features is the ability to have multiple session files for a given project, by using git branches. To enable git branching:
@ -209,7 +210,7 @@ require("persisted").setup({
}) })
``` ```
### Autosaving **Autosaving**
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 save a Neovim session to disk when the `VimLeavePre` event is triggered. Autosaving can be turned off by:
@ -240,7 +241,7 @@ Of course, if you wish to manually save the session when autosaving is disabled,
> [!NOTE] > [!NOTE]
> If `autosave = false` then the `should_autosave` callback will not be executed. > If `autosave = false` then the `should_autosave` callback will not be executed.
### Autoloading **Autoloading**
The plugin can be enabled to automatically load sessions when Neovim is started. Whilst off by default, this can be turned on by: The plugin can be enabled to automatically load sessions when Neovim is started. Whilst off by default, this can be turned on by:
@ -266,7 +267,7 @@ Autoloading can be further controlled for certain directories by specifying `all
> [!NOTE] > [!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. > 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 **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`. 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`.
@ -281,7 +282,7 @@ require("persisted").setup({
> [!NOTE] > [!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`. > 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 **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 autosave and/or autoload from. For example:
@ -299,7 +300,7 @@ Specifying `~/Code` will autosave and autoload from that directory as well as al
> [!NOTE] > [!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 `autosave` and/or `autoload` are set to `true`, then the plugin will autoload/autosave from _any_ directory
### Ignored directories **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** autosave and autoload from. For example:
@ -329,7 +330,7 @@ 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. 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 **Ignored branches**
You may specify a table of patterns that match against branches for which the plugin will **never** autosave and autoload from: You may specify a table of patterns that match against branches for which the plugin will **never** autosave and autoload from:
@ -342,7 +343,7 @@ require("persisted").setup({
}) })
``` ```
### Events / Callbacks **Events / Callbacks**
The plugin fires events at various points during its lifecycle: The plugin fires events at various points during its lifecycle:
@ -359,8 +360,6 @@ The plugin fires events at various points during its lifecycle:
These events can be consumed anywhere within your configuration by utilising the `vim.api.nvim_create_autocmd` function. These events can be consumed anywhere within your configuration by utilising the `vim.api.nvim_create_autocmd` function.
#### Example use case
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: 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 ```lua
@ -379,7 +378,7 @@ vim.api.nvim_create_autocmd({ "User" }, {
}) })
``` ```
#### Using callback data **Using callback data**
When certain events are fired, session data is made available for the user to consume, for example: When certain events are fired, session data is made available for the user to consume, for example:

58
doc/persisted.nvim.txt
View File

@ -76,8 +76,7 @@ recommended that you give this plugin a greater loading priority. With
**Packer** the `after` config option can be used and in **Lazy.nvim**, the **Packer** the `after` config option can be used and in **Lazy.nvim**, the
`priority` property. `priority` property.
**Telescope extension**
TELESCOPE EXTENSION ~
Ensure that the telescope extension is loaded with: Ensure that the telescope extension is loaded with:
@ -103,8 +102,7 @@ The layout can then be customised from within Telescope:
USAGE *persisted.nvim-usage* USAGE *persisted.nvim-usage*
**Commands**
COMMANDS ~
The plugin comes with a number of commands: The plugin comes with a number of commands:
@ -118,8 +116,7 @@ The plugin comes with a number of commands:
- `:SessionLoadFromFile` - Load a session from a given path - `:SessionLoadFromFile` - Load a session from a given path
- `:SessionDelete` - Delete the current session - `:SessionDelete` - Delete the current session
**Telescope extension**
TELESCOPE EXTENSION ~
The Telescope extension may be opened via `:Telescope persisted`. The available The Telescope extension may be opened via `:Telescope persisted`. The available
actions are: actions are:
@ -130,8 +127,7 @@ actions are:
- `<C-c>` - Copy the session file - `<C-c>` - Copy the session file
- `<C-d>` - Delete the session file - `<C-d>` - Delete the session file
**Global variables**
GLOBAL VARIABLES ~
The plugin sets a number of global variables throughout its lifecycle: The plugin sets a number of global variables throughout its lifecycle:
@ -143,13 +139,13 @@ The plugin sets a number of global variables throughout its lifecycle:
CONFIGURATION *persisted.nvim-configuration* CONFIGURATION *persisted.nvim-configuration*
**Defaults**
DEFAULTS ~
The plugin comes with the following defaults: The plugin comes with the following defaults:
>lua >lua
require("persisted").setup({ 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 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 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 use_git_branch = false, -- create session files based on the branch of a git enabled repository
@ -170,16 +166,15 @@ The plugin comes with the following defaults:
delete_session = "<c-d>", delete_session = "<c-d>",
}, },
icons = { -- icons displayed in the picker, set to nil to disable entirely icons = { -- icons displayed in the picker, set to nil to disable entirely
branch = " ", branch = " ",
dir = " ", dir = " ",
selected = " ", selected = " ",
}, },
}, },
}) })
< <
**What is saved in the session?**
WHAT IS SAVED IN THE SESSION? ~
As the plugin uses Vim’s `:mksession` command then you may change the 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. `vim.o.sessionoptions` value to determine what to write into the session.
@ -188,8 +183,7 @@ Please see `:h sessionoptions` for more information.
[!NOTE] The author uses: `vim.o.sessionoptions = [!NOTE] The author uses: `vim.o.sessionoptions =
"buffers,curdir,folds,tabpages,winpos,winsize"` "buffers,curdir,folds,tabpages,winpos,winsize"`
**Session save location**
SESSION SAVE LOCATION ~
The location of the session files may be changed by altering the `save_dir` The location of the session files may be changed by altering the `save_dir`
configuration option. For example: configuration option. For example:
@ -203,8 +197,7 @@ configuration option. For example:
[!NOTE] The plugin may be unable to find existing sessions if the `save_dir` [!NOTE] The plugin may be unable to find existing sessions if the `save_dir`
value is changed value is changed
**Git branching**
GIT BRANCHING ~
One of the plugin’s core features is the ability to have multiple session One of the plugin’s core features is the ability to have multiple session
files for a given project, by using git branches. To enable git branching: files for a given project, by using git branches. To enable git branching:
@ -215,8 +208,7 @@ files for a given project, by using git branches. To enable git branching:
}) })
< <
**Autosaving**
AUTOSAVING ~
By default, the plugin will automatically save a Neovim session to disk when By default, the plugin will automatically save a Neovim session to disk when
the `VimLeavePre` event is triggered. Autosaving can be turned off by: the `VimLeavePre` event is triggered. Autosaving can be turned off by:
@ -252,8 +244,7 @@ disabled, the `:SessionSave` command can be used.
[!NOTE] If `autosave = false` then the `should_autosave` callback will not be [!NOTE] If `autosave = false` then the `should_autosave` callback will not be
executed. executed.
**Autoloading**
AUTOLOADING ~
The plugin can be enabled to automatically load sessions when Neovim is The plugin can be enabled to automatically load sessions when Neovim is
started. Whilst off by default, this can be turned on by: started. Whilst off by default, this can be turned on by:
@ -284,8 +275,7 @@ Autoloading can be further controlled for certain directories by specifying
Neovim with arguments other than a single directory argument. For example: Neovim with arguments other than a single directory argument. For example:
`nvim some_file.rb` will not result in autoloading but `nvim `nvim some_file.rb` will not result in autoloading but `nvim
some/existing/path` or `nvim .` will. some/existing/path` or `nvim .` will.
**Following current working directory**
FOLLOWING CURRENT WORKING DIRECTORY ~
There may be a need to change the working directory to quickly access files in 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 other directories without changing the current session’s name on save. This
@ -304,8 +294,7 @@ By default, the session name will match the current working directory:
the global variable `vim.g.persisting_session`. This variable can be manually the global variable `vim.g.persisting_session`. This variable can be manually
adjusted if changes to the session name are needed. Alternatively, if adjusted if changes to the session name are needed. Alternatively, if
`follow_cwd = true` then `vim.g.persisting_session = nil`. `follow_cwd = true` then `vim.g.persisting_session = nil`.
**Allowed directories**
ALLOWED DIRECTORIES ~
You may specify a table of directories for which the plugin will autosave You may specify a table of directories for which the plugin will autosave
and/or autoload from. For example: and/or autoload from. For example:
@ -326,8 +315,7 @@ all its sub-directories.
[!NOTE] If `allowed_dirs` is left at its default value and `autosave` and/or [!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_ `autoload` are set to `true`, then the plugin will autoload/autosave from _any_
directory directory
**Ignored directories**
IGNORED DIRECTORIES ~
You may specify a table of directories for which the plugin will **never** You may specify a table of directories for which the plugin will **never**
autosave and autoload from. For example: autosave and autoload from. For example:
@ -363,8 +351,7 @@ In this setup, `~/.config` and `~/.local/nvim` are still going to behave in
their default setting (ignoring all listed directory and its children), however their default setting (ignoring all listed directory and its children), however
`/` and `/tmp` will only ignore those directories exactly. `/` and `/tmp` will only ignore those directories exactly.
**Ignored branches**
IGNORED BRANCHES ~
You may specify a table of patterns that match against branches for which the You may specify a table of patterns that match against branches for which the
plugin will **never** autosave and autoload from: plugin will **never** autosave and autoload from:
@ -378,8 +365,7 @@ plugin will **never** autosave and autoload from:
}) })
< <
**Events / Callbacks**
EVENTS / CALLBACKS ~
The plugin fires events at various points during its lifecycle: The plugin fires events at various points during its lifecycle:
@ -398,9 +384,6 @@ The plugin fires events at various points during its lifecycle:
These events can be consumed anywhere within your configuration by utilising These events can be consumed anywhere within your configuration by utilising
the `vim.api.nvim_create_autocmd` function. the `vim.api.nvim_create_autocmd` function.
EXAMPLE USE CASE
A commonly requested example is to use the Telescope extension to load a 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: session, saving the current session before clearing all of the open buffers:
@ -420,8 +403,7 @@ session, saving the current session before clearing all of the open buffers:
}) })
< <
**Using callback data**
USING CALLBACK DATA
When certain events are fired, session data is made available for the user to When certain events are fired, session data is made available for the user to
consume, for example: consume, for example: