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

docs: update README.md

main
olimorris 2024-02-24 12:05:57 +00:00
parent edd8aa41cd
commit 86a55a1d4c
2 changed files with 31 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
README.md
View File

@ -47,7 +47,8 @@ Install the plugin with your preferred package manager:
} }
``` ```
> **Note**: The `lazy = true` option may be useful if you use a dashboard > [!NOTE]
> The `lazy = true` option may be useful if you use a dashboard
**[Packer](https://github.com/wbthomason/packer.nvim)** **[Packer](https://github.com/wbthomason/packer.nvim)**
@ -170,8 +171,8 @@ require("persisted").setup({
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**: The author uses: > [!NOTE]
> `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
@ -183,7 +184,8 @@ require("persisted").setup({
}) })
``` ```
> **Note**: The plugin may be unable to find existing sessions if the `save_dir` value is changed > [!NOTE]
> The plugin may be unable to find existing sessions if the `save_dir` value is changed
### Git branching ### Git branching
@ -223,7 +225,8 @@ require("persisted").setup({
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 when autosaving is disabled, the `:SessionSave` command can be used.
> **Note**: If `autosave = false` then the `should_autosave` callback will not be executed. > [!TIP]
> If `autosave = false` then the `should_autosave` callback will not be executed.
### Autoloading ### Autoloading
@ -248,7 +251,8 @@ require("persisted").setup({
Autoloading can be further controlled for certain directories by specifying `allowed_dirs` and `ignored_dirs`. Autoloading can be further controlled for certain directories by specifying `allowed_dirs` and `ignored_dirs`.
> **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. > [!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 ### Following current working directory
@ -262,7 +266,8 @@ require("persisted").setup({
}) })
``` ```
> **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`. > [!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 ### Allowed directories
@ -279,7 +284,8 @@ require("persisted").setup({
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.
> **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 `autosave` and/or `autoload` are set to `true`, then the plugin will autoload/autosave from _any_ directory
### Ignored directories ### Ignored directories
@ -373,7 +379,8 @@ vim.api.nvim_create_autocmd({ "User" }, {
}) })
``` ```
> **Note**: This data is available for the `PersistedLoad`, `PersistedDelete` and `PersistedTelescope` events > [!NOTE]
> This data is available for the `PersistedLoad`, `PersistedDelete` and `PersistedTelescope` events
## :page_with_curl: License ## :page_with_curl: License

24
doc/persisted.nvim.txt
View File

@ -12,6 +12,7 @@ Table of Contents *persisted.nvim-table-of-contents*
FEATURES *persisted.nvim-features* FEATURES *persisted.nvim-features*
- Supports sessions across multiple git branches - Supports sessions across multiple git branches
- Telescope extension to work with saved sessions - Telescope extension to work with saved sessions
- Custom events which users can hook into for tighter integration - Custom events which users can hook into for tighter integration
@ -22,6 +23,7 @@ FEATURES *persisted.nvim-features*
REQUIREMENTS *persisted.nvim-requirements* REQUIREMENTS *persisted.nvim-requirements*
- Neovim >= 0.8.0 - Neovim >= 0.8.0
@ -40,7 +42,7 @@ Install the plugin with your preferred package manager:
< <
**Note**The `lazy = true` option may be useful if you use a dashboard [!NOTE] The `lazy = true` option may be useful if you use a dashboard
**Packer** **Packer**
>lua >lua
@ -105,6 +107,7 @@ COMMANDS ~
The plugin comes with a number of commands: The plugin comes with a number of commands:
- `:SessionToggle` - Determines whether to load, start or stop a session - `: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 `autosave = false`
- `:SessionStop` - Stop recording a session - `:SessionStop` - Stop recording a session
@ -120,6 +123,7 @@ 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:
- `<CR>` - Open/source the session file - `<CR>` - Open/source the session file
- `<C-b>` - Add/update the git branch for the session file - `<C-b>` - Add/update the git branch for the session file
- `<C-c>` - Copy the session file - `<C-c>` - Copy the session file
@ -130,6 +134,7 @@ GLOBAL VARIABLES ~
The plugin sets a number of global variables throughout its lifecycle: 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.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_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.persisted_loaded_session` - (string) The file path to the current session
@ -166,10 +171,10 @@ 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.
Please see |sessionoptions| for more information. 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 ~
@ -184,7 +189,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 ~
@ -233,7 +238,7 @@ Of course, if you wish to manually save the session when autosaving is
disabled, the `:SessionSave` command can be used. disabled, the `:SessionSave` command can be used.
**Note**If `autosave = false` then the `should_autosave` callback will not be [!TIP] If `autosave = false` then the `should_autosave` callback will not be
executed. executed.
AUTOLOADING ~ AUTOLOADING ~
@ -263,7 +268,7 @@ Autoloading can be further controlled for certain directories by specifying
`allowed_dirs` and `ignored_dirs`. `allowed_dirs` and `ignored_dirs`.
**Note**Autoloading will not occur if the plugin is lazy loaded or a user opens [!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: 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.
@ -283,7 +288,7 @@ By default, the session name will match the current working directory:
< <
**Note**If `follow_cwd = false` the session name is stored upon loading under [!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 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`.
@ -306,7 +311,7 @@ Specifying `~/Code` will autosave and autoload from that directory as well as
all its sub-directories. 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
@ -351,6 +356,7 @@ EVENTS / CALLBACKS ~
The plugin fires events at various points during its lifecycle: The plugin fires events at various points during its lifecycle:
- `PersistedLoadPre` - For _before_ a session is loaded - `PersistedLoadPre` - For _before_ a session is loaded
- `PersistedLoadPost` - For _after_ a session is loaded - `PersistedLoadPost` - For _after_ a session is loaded
- `PersistedTelescopeLoadPre` - For _before_ a session is loaded via Telescope - `PersistedTelescopeLoadPre` - For _before_ a session is loaded via Telescope
@ -415,7 +421,7 @@ To consume this data, use the `session.data` table in your autocmd:
< <
**Note**This data is available for the `PersistedLoad`, `PersistedDelete` and [!NOTE] This data is available for the `PersistedLoad`, `PersistedDelete` and
`PersistedTelescope` events `PersistedTelescope` events
LICENSE *persisted.nvim-license* LICENSE *persisted.nvim-license*