feat: improve README.md
olimorris
parent
ba5f0ab091
commit
b6201178ff
166
README.md
166
README.md
|
|
@ -1,4 +1,4 @@
|
|||
# 💾 Persisted
|
||||
# :floppy_disk: Persisted
|
||||
|
||||
 [](https://github.com/olimorris/persisted.nvim/actions/workflows/ci.yml)
|
||||
|
||||
|
|
@ -6,19 +6,41 @@
|
|||
|
||||
The plugin was forked from the fantastic [Persistence.nvim](https://github.com/folke/persistence.nvim) as active development seems to have been paused and there were some useful pull requests.
|
||||
|
||||
## ✨ Features
|
||||
## :book: Table of Contents
|
||||
|
||||
- [Features](#sparkles-features)
|
||||
- [Requirements](#zap-requirements)
|
||||
- [Installation](#package-installation)
|
||||
- [Configuration](#wrench-configuration)
|
||||
- [Defaults](#defaults)
|
||||
- [Session options](#session-options)
|
||||
- [Session save location](#session-save-location)
|
||||
- [Git branching](#git-branching)
|
||||
- [Autosaving](#autosaving)
|
||||
- [Autoloading](#autoloading)
|
||||
- [Allowed directories](#allowed-directories)
|
||||
- [Ignored directories](#ignored-directories)
|
||||
- [Callbacks](#callbacks)
|
||||
- [Telescope extension](#telescope-extension)
|
||||
- [Usage](#rocket-usage)
|
||||
- [Commands](#commands)
|
||||
- [Lazy loading](#lazy-loading)
|
||||
- [Helpers](#helpers)
|
||||
- [License](#page_with_curl-license)
|
||||
|
||||
## :sparkles: 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)
|
||||
- Support for sessions across git branches
|
||||
- Specify custom directory to save/load sessions from
|
||||
- Telescope extension to list all sessions
|
||||
|
||||
## ⚡️ Requirements
|
||||
## :zap: Requirements
|
||||
|
||||
- Neovim >= 0.6.0
|
||||
|
||||
## 📦 Installation
|
||||
## :package: Installation
|
||||
|
||||
Install the plugin with your preferred package manager:
|
||||
|
||||
|
|
@ -31,6 +53,7 @@ use({
|
|||
--module = "persisted", -- Consider lazy loading if you use a dashboard or startup screen
|
||||
config = function()
|
||||
require("persisted").setup()
|
||||
require("telescope").load_extension("persisted") -- To load the telescope extension
|
||||
end,
|
||||
})
|
||||
```
|
||||
|
|
@ -50,7 +73,9 @@ lua << EOF
|
|||
EOF
|
||||
```
|
||||
|
||||
## ⚙️ Configuration
|
||||
## :wrench: Configuration
|
||||
|
||||
### Defaults
|
||||
|
||||
The plugin comes with the following defaults:
|
||||
|
||||
|
|
@ -64,22 +89,124 @@ The plugin comes with the following defaults:
|
|||
ignored_dirs = nil, -- table of dirs that are ignored when auto-saving and auto-loading
|
||||
before_save = function() end, -- function to run before the session is saved to disk
|
||||
after_save = function() end, -- function to run after the session is saved to disk
|
||||
telescope = { -- options for the telescope extension
|
||||
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
|
||||
},
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
These can be overwritten by calling the `setup` method and passing in the appropriate value.
|
||||
### Session options
|
||||
|
||||
> **Note:** The plugin uses 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:** `autosave` and `autoload` may not work if you've lazy loaded the plugin.
|
||||
> **Note:** The author uses `vim.o.sessionoptions = "buffers,curdir,folds,winpos,winsize"`
|
||||
|
||||
## 🚀 Usage
|
||||
### Session save location
|
||||
|
||||
The plugin is designed to work with startup screens like [vim-startify](https://github.com/mhinz/vim-startify) or [dashboard](https://github.com/glepnir/dashboard-nvim) out of the box. It will never load a session automatically by default. However, if you are using a startup screen plugin, consider lazy loading the plugin (see the **Helpers** section). This prevents unintentional session auto-saves when on the startup screen.
|
||||
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`.
|
||||
|
||||
To use the plugin, the commands below are available:
|
||||
> **Note:** If you change the `dir` value and try to restore sessions, the plugin will be unable to find existing ones
|
||||
|
||||
### 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`.
|
||||
|
||||
> **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. This action is only undertaken when the user quits Neovim. This can be turned off by setting `autosave = false`.
|
||||
|
||||
Autosaving can be further controlled by specifying `allowed_dirs` and `ignored_dirs`. See the section below for more information.
|
||||
|
||||
### 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`.
|
||||
|
||||
Autoloading can be further controlled by specifying `allowed_dirs` and `ignored_dirs`. See the section below for more information.
|
||||
|
||||
> **Note:** Autoloading will not occur if a user opens Neovim with arguments such as `nvim some_file.rb`
|
||||
|
||||
### Allowed directories
|
||||
|
||||
You may specify a table of directories for which the plugin will autosave and/or autoload from. For example:
|
||||
|
||||
```lua
|
||||
{
|
||||
allowed_dirs = {
|
||||
"~/Code/Neovim",
|
||||
"~/Code/Projects/Ruby
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** If `allowed_dirs` is set, then the plugin will only autosave and/or autoload from the specificed 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
|
||||
|
||||
### Ignoring directories
|
||||
|
||||
You may specify a table of directories for which the plugin will **never** autosave and/or autoload from. For example:
|
||||
|
||||
```lua
|
||||
{
|
||||
ignored_dirs = {
|
||||
"~/.config",
|
||||
"~/.local/nvim"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Callbacks
|
||||
|
||||
The plugin allows for *before* and *after* callbacks to be executed before a session is saved. This is achieved via the `before_save` and `after_save` configuration options. For example:
|
||||
|
||||
```lua
|
||||
{
|
||||
before_save = function()
|
||||
pcall(vim.cmd, "bw minimap")
|
||||
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
|
||||
|
||||
### Telescope extension
|
||||
|
||||
> **This feature is still in beta!!**
|
||||
|
||||
The plugin contains an extension for [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim) which allows the user to list all of the saved session files and source them.
|
||||
|
||||
#### Telescope callbacks
|
||||
|
||||
The plugin allows for *before* and *after* callbacks to be used when sourcing a session via *Telescope*. For example:
|
||||
|
||||
```lua
|
||||
{
|
||||
telescope = {
|
||||
before_source = function()
|
||||
-- Close all open buffers
|
||||
pcall(vim.cmd, "bufdo bwipeout")
|
||||
end,
|
||||
after_source = function(session)
|
||||
print("Session " .. session.name .. " loaded for the " .. session.branch .. " branch")
|
||||
end,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
A *session* table is exposed to the callback functions and has the following properties:
|
||||
* name - The filename of the session.
|
||||
* branch - The git branch of the session.
|
||||
* pwd - The present working directory of the session; *and*
|
||||
* file_path - The file path to the session.
|
||||
|
||||
## :rocket: Usage
|
||||
|
||||
### Commands
|
||||
The plugin comes with a number of commands:
|
||||
|
||||
- `SessionStart` - Start recording a session. Useful if `autosave = false`
|
||||
- `SessionStop` - Stop recording a session
|
||||
|
|
@ -90,24 +217,17 @@ To use the plugin, the commands below are available:
|
|||
- `SessionToggle` - Determines whether to load, start or stop a session
|
||||
|
||||
> **Note:** The author only binds `SessionToggle` to a keymap for simplicity.
|
||||
> **Remember:** These will not work out of the box if you're lazy loading.
|
||||
|
||||
### Callbacks
|
||||
|
||||
The plugin allows for _before_ and _after_ callbacks to be executed relative to the session being saved. This is achieved via the `before_save` and `after_save` configuration options.
|
||||
|
||||
> **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.
|
||||
|
||||
### Lazy loading
|
||||
|
||||
To lazy load the plugin, consider adding the `module = "persisted"` option if you're using packer. The commands may then be called with `<cmd>lua require("persisted").start()<cr>` for example. The only command which is nuanced is `SessionLoadLast` which is called with `<cmd>lua require("persisted").load({ last = true })<cr>`.
|
||||
The plugin is designed to work with startup screens like [vim-startify](https://github.com/mhinz/vim-startify) or [dashboard](https://github.com/glepnir/dashboard-nvim) 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.
|
||||
|
||||
### 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](https://github.com/olimorris/dotfiles/blob/0cdaee183c64f872778952f90f62b9366851101c/.config/nvim/lua/Oli/plugins/statusline.lua#L257).
|
||||
|
||||
A table of saved sessions can be returned by the `lua require("persisted").list()` command. The author uses this to display a list of sessions in their [config](https://github.com/olimorris/dotfiles/blob/9e06f00a878710aefc8c28904d2322ea46e3eaea/.config/nvim/lua/Oli/core/functions.lua#L3).
|
||||
|
||||
## :page_with_curl: License
|
||||
|
||||
[MIT](https://github.com/olimorris/persisted.nvim/blob/main/LICENSE)
|
||||
|
|
|
|||
|
|
@ -11,5 +11,5 @@ runtime plugin/plenary.vim
|
|||
command Setup PlenaryBustedDirectory tests/setup {minimal_init = 'tests/minimal.vim'}
|
||||
command TestAutoloading PlenaryBustedDirectory tests/autoload {minimal_init = 'tests/minimal.vim'}
|
||||
command TestGitBranching PlenaryBustedDirectory tests/git_branching {minimal_init = 'tests/minimal.vim'}
|
||||
command Test PlenaryBustedFile tests/default_settings_spec.lua
|
||||
command TestDefaults PlenaryBustedFile tests/default_settings_spec.lua
|
||||
command TearDown PlenaryBustedFile tests/teardown/clean_up_dirs.lua
|
||||
|
|
|
|||
Loading…
Reference in New Issue