chore: update README.md

main
olimorris 2022-04-22 12:15:41 +01:00
parent 637e1a5d8f
commit ec388c54ee
1 changed files with 44 additions and 16 deletions

View File

@ -81,7 +81,7 @@ EOF
The plugin comes with the following defaults: The plugin comes with the following defaults:
```lua ```lua
{ require("persisted").setup({
dir = vim.fn.expand(vim.fn.stdpath("data") .. "/sessions/"), -- directory where session files are saved dir = vim.fn.expand(vim.fn.stdpath("data") .. "/sessions/"), -- directory where session files are saved
use_git_branch = false, -- create session files based on the branch of the git enabled repository 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 autosave = true, -- automatically save session files when exiting Neovim
@ -94,7 +94,7 @@ The plugin comes with the following defaults:
before_source = function(session) end, -- function to run before the session is sourced via telescope before_source = function(session) end, -- function to run before the session is sourced via telescope
after_source = function(session) end, -- function to run after the session is sourced via telescope after_source = function(session) end, -- function to run after the session is sourced via telescope
}, },
} })
``` ```
### Session options ### Session options
@ -105,25 +105,50 @@ As the plugin uses Vim's `:mksession` command then you may change the `vim.o.ses
### Session save location ### Session save location
The location of the saved files for the sessions may be changed by altering the `dir` configuration option. By default, the plugin will save to `~/.local/share/nvim/sessions`. The location of the saved files for the sessions may be changed by altering the `dir` configuration option. For example:
```lua
require("persisted").setup({
dir = vim.fn.expand(vim.fn.stdpath("data") .. "/sessions/"), -- Resolves to ~/.local/share/nvim/sessions
})
```
> **Note:** If you change the `dir` value and try to restore sessions, the plugin will be unable to find existing ones > **Note:** If you change the `dir` value and try to restore sessions, the plugin will be unable to find existing ones
### Git branching ### 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, set `use_git_branch = true`. 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 > **Note:** If git branching is enabled on a non git enabled repo, then `main` will be used as the default branch
### Autosaving ### Autosaving
By default, the plugin will automatically save a Neovim session to disk. This action is only undertaken when the user quits Neovim. This can be turned off by setting `autosave = false`. By default, the plugin will automatically save a Neovim session to disk. This action is only undertaken when the user quits Neovim. This can be turned off by:
```lua
require("persisted").setup({
autosave = false,
})
```
Autosaving can be further controlled by specifying `allowed_dirs` and `ignored_dirs`. Autosaving can be further controlled by specifying `allowed_dirs` and `ignored_dirs`.
### 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 setting `autoload = true`. 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,
})
```
Autoloading can be further controlled by specifying `allowed_dirs` and `ignored_dirs`. Autoloading can be further controlled by specifying `allowed_dirs` and `ignored_dirs`.
@ -134,12 +159,12 @@ Autoloading can be further controlled by specifying `allowed_dirs` and `ignored_
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:
```lua ```lua
{ require("persisted").setup({
allowed_dirs = { allowed_dirs = {
"~/.dotfiles", "~/.dotfiles",
"~/Code", "~/Code",
} },
} })
``` ```
Specifying `~/Code` will autosave and autoload from that directory as well as all its sub-directories. Specifying `~/Code` will autosave and autoload from that directory as well as all its sub-directories.
@ -151,12 +176,12 @@ Specifying `~/Code` will autosave and autoload from that directory as well as al
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:
```lua ```lua
{ require("persisted").setup({
ignored_dirs = { ignored_dirs = {
"~/.config", "~/.config",
"~/.local/nvim" "~/.local/nvim"
} },
} })
``` ```
Specifying `~/.config` will prevent any autosaving and autoloading from that directory as well as all its sub-directories. Specifying `~/.config` will prevent any autosaving and autoloading from that directory as well as all its sub-directories.
@ -166,11 +191,14 @@ Specifying `~/.config` will prevent any autosaving and autoloading from that dir
The plugin allows for *before* and *after* callbacks to be executed before and after a session is saved. This is achieved via the `before_save` and `after_save` configuration options. For example: The plugin allows for *before* and *after* callbacks to be executed before and after a session is saved. This is achieved via the `before_save` and `after_save` configuration options. For example:
```lua ```lua
{ require("persisted").setup({
before_save = function() before_save = function()
pcall(vim.cmd, "bw minimap") pcall(vim.cmd, "bw minimap")
end, end,
} after_save = function()
-- Do something
end,
})
``` ```
> **Note:** The author uses a *before* callback to ensure that [minimap.vim](https://github.com/wfxr/minimap.vim) is not written into the session. Its presence prevents the exact buffer and cursor position from being restored when loading a session > **Note:** The author uses a *before* callback to ensure that [minimap.vim](https://github.com/wfxr/minimap.vim) is not written into the session. Its presence prevents the exact buffer and cursor position from being restored when loading a session
@ -186,7 +214,7 @@ The plugin contains an extension for [telescope.nvim](https://github.com/nvim-te
The plugin allows for *before* and *after* callbacks to be used when sourcing a session via *Telescope*. For example: The plugin allows for *before* and *after* callbacks to be used when sourcing a session via *Telescope*. For example:
```lua ```lua
{ require("persisted").setup({
telescope = { telescope = {
before_source = function() before_source = function()
-- Close all open buffers -- Close all open buffers
@ -196,7 +224,7 @@ The plugin allows for *before* and *after* callbacks to be used when sourcing a
print("Session " .. session.name .. " loaded for the " .. session.branch .. " branch") print("Session " .. session.name .. " loaded for the " .. session.branch .. " branch")
end, end,
}, },
} })
``` ```
A *session* table is exposed to the callback functions and has the following properties: A *session* table is exposed to the callback functions and has the following properties: